@intentcomputing/koko-agent-sdk 1.0.1 → 1.1.1

package/docs/CONFIGURATION.zh-CN.md

@@ -0,0 +1,195 @@
+# SDK 完整配置参考
+
+> English: [CONFIGURATION.md](./CONFIGURATION.md)
+
+本文覆盖宿主接入时可配置的公开接口：`KokoProvider`、`KokoAgentConfig`、运行时外观、单次任务参数，以及内置 UI 组件。TypeScript 类型定义仍是最终准源。
+
+## 完整示例
+
+```tsx
+import React from 'react';
+import {
+  KokoProvider,
+  openKokoChat,
+  setKokoAppearance,
+} from '@intentcomputing/koko-agent-sdk';
+
+export function App() {
+  const tokenProvider = React.useCallback(async () => {
+    const response = await hostApi.get('/koko/access-token');
+    return response.data as { accessToken: string; expiresAt: number };
+  }, []);
+
+  return (
+    <KokoProvider
+      cursor
+      observer
+      dialogs
+      resumeAfterReload
+      config={{
+        gateway: {
+          baseUrl: 'https://sdk.intentcomputing.cn',
+          tokenProvider,
+          // appId 通常无需填写，默认读取 Bundle ID / Package Name。
+        },
+        locale: 'zh',
+        theme: 'light', // 填宿主主题；Koko 浮层会使用对比主题。
+        branding: {
+          name: 'My Assistant',
+          tagline: '帮你操作当前 App',
+          placeholder: '告诉我你想做什么…',
+          primaryColor: '#6D4AFF',
+          icon: require('./assistant.png'),
+        },
+        confirmation: {
+          requireUserConfirm: true,
+          mode: 'preflight',
+        },
+        webWalletAliases: ['My Wallet'],
+        dumpMaxDepth: 80,
+        dumpSkipInvisible: true,
+        cursorDurationMs: 480,
+        observer: true,
+        debug: false,
+        onUsageEvent: event => analytics.track('koko_usage', event),
+      }}
+    >
+      <HostNavigation />
+    </KokoProvider>
+  );
+}
+```
+
+## `KokoProvider` props
+
+| 配置 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `children` | `ReactNode` | 必填 | 宿主应用或最外层导航树。 |
+| `config` | `KokoAgentConfig` | `{}` | Agent、网关、品牌和确认策略，详见下表。 |
+| `cursor` | `boolean` | `true` | 显示可观测操作光标。 |
+| `observer` | `boolean` | 继承 `config.observer` | 显示任务进度条和对话面板宿主；显式传入时优先。 |
+| `dialogs` | `boolean` | `true` | 挂载 SDK 内置确认和追问弹窗。关闭后，宿主应提供对应回调。 |
+| `resumeAfterReload` | `boolean` | `true` | JS 上下文因语言、主题或宿主重载而中断时，最多恢复一次最近任务。 |
+| `remoteSmokePort` | `number` | `0` | 仅供开发联调的本机 smoke 驱动端口；生产包不要配置。 |
+| `composerPlaceholder` | `string` | — | 已废弃；改用 `config.branding.placeholder`。 |
+
+`KokoProvider.observer={false}` 只隐藏内置进度/对话 UI；`config.observer={false}` 还会关闭自动任务日志。两者都为 `true` 时功能完整。
+
+## `KokoAgentConfig`
+
+| 配置 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `gateway` | `GatewayConfig` | — | 正式运行必需的网关和短 Token 配置。 |
+| `locale` | `'zh' \| 'en'` | `'en'` | SDK 内置 UI 初始语言。运行时变化优先使用 `setKokoAppearance`。 |
+| `theme` | `'light' \| 'dark'` | `'light'` | **宿主 App 当前主题**；Koko 浮层会使用相反主题以保持可见。 |
+| `branding` | `KokoBrandingConfig` | Koko 默认品牌 | 自定义名称、图标、文案和主色；需要 `custom_branding` 权益。 |
+| `confirmation` | `ConfirmationPolicy` | 需要确认、`preflight` | 高风险任务的人工确认策略。 |
+| `onConfirmSensitive` | `(ctx) => Promise<boolean>` | 内置确认弹窗 | 自定义敏感操作确认。返回 `true` 才继续。 |
+| `webWalletAliases` | `string[]` | `[]` | 宿主确认属于自身注入钱包的公开钱包名称。只声明已验证别名。 |
+| `dumpMaxDepth` | `number` | `80` | 原生可访问性树最大读取深度；过小会截断 RN 导航/组件库下的页面正文。 |
+| `dumpSkipInvisible` | `boolean` | `true` | 读取页面时丢弃不可见节点。 |
+| `cursorDurationMs` | `number` | `480` | 默认光标移动动画时长，单位毫秒。 |
+| `observer` | `boolean` | `true` | 启用任务日志；Provider 未显式设置 `observer` 时也控制内置进度/对话 UI。 |
+| `debug` | `boolean` | Metro Debug 为 `true`；Release 为 `false` | 输出能力和执行步骤日志，不放宽安全策略。正式包建议显式设为 `false`。 |
+| `devMode` | `boolean` | 同 `debug` | 已废弃的 `debug` 别名。 |
+| `onUsageEvent` | `(event) => void` | — | 本地分析/UX 事件旁路通知，不参与计费，也不能阻塞任务。 |
+
+### `gateway`
+
+| 配置 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `baseUrl` | `string` | `https://sdk.intentcomputing.net` | 海外/OpenAI 网关；国内/DeepSeek 使用 `https://sdk.intentcomputing.cn`。正式构建只接受官方地址。 |
+| `tokenProvider` | `() => Promise<string \| { accessToken; expiresAt? }>` | — | 推荐。向**宿主后端**获取短期 Token。SDK 仅在内存中缓存，在请求时发现临近过期才刷新，401 后强制刷新并重试一次。 |
+| `token` | `string` | — | 旧版静态 Token，仅用于本地开发和迁移；不要放进正式包。 |
+| `appId` | `string` | 原生 Bundle ID / Package Name | 必须与服务端登记的宿主应用一致；通常无需手填。 |
+
+`tokenProvider` 返回对象时，`expiresAt` 使用 Unix **毫秒**。若省略，SDK 尝试读取 JWT `exp`；两者都没有时按 60 秒处理。`clientSecret`、DeepSeek/OpenAI Key 永远不得进入 App。
+
+### `branding`
+
+| 配置 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `name` | `string` | `Koko` | 助手显示名称。 |
+| `icon` | `number \| { uri: string } \| string` | 默认 K 标记 | 支持 `require()`、图片 URI/Data URI 或短文字标记。 |
+| `tagline` | `string` | 本地化默认文案 | 对话页副标题。 |
+| `placeholder` | `string` | 本地化默认文案 | 输入框占位文案。 |
+| `primaryColor` | `string` | SDK 默认主色 | Badge、发送按钮等强调色。使用 React Native 可识别的颜色字符串。 |
+
+没有品牌权益时，SDK 自动降级到 Koko 默认品牌，并通过 `onUsageEvent` 发出一次 `branding_downgraded`。
+
+### `confirmation`
+
+| 配置 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `requireUserConfirm` | `boolean` | `true` | 是否要求高风险目标由用户确认。 |
+| `mode` | `'preflight' \| 'inline' \| 'off'` | `'preflight'` | `preflight` 在任务开始前确认一次；`inline` 为兼容旧版的逐步确认；`off` 关闭 SDK 确认。 |
+| `sensitivePatterns` | `RegExp[]` | SDK 内置规则 | 自定义高风险目标匹配规则。传入非空数组时替换内置规则。 |
+
+关闭 SDK 确认不会绕过密码、助记词、私钥、OTP 等隐私页面的本地门禁；这些内容仍必须由用户亲自操作。
+
+### `onUsageEvent` 事件
+
+可能收到：`task_started`、`task_finished`、`agent_step`、`quota_exceeded`、`sheet_opened`、`sheet_closed`、`branding_downgraded`。不得把事件里的任务文本继续发送到未经授权的分析服务。
+
+## 运行时语言和主题
+
+```tsx
+import { setKokoAppearance } from '@intentcomputing/koko-agent-sdk';
+
+useEffect(() => {
+  setKokoAppearance({ locale: hostLocale, theme: hostTheme });
+}, [hostLocale, hostTheme]);
+```
+
+- `locale` 可传宿主语言字符串；以 `zh` 开头映射为中文，其余映射为英文。
+- `theme` 填宿主真实主题：`'light'` 或 `'dark'`。
+- 运行时外观优先级高于静态 `config.locale` / `config.theme`。
+
+`getKokoAgent().configure(patch)` 可动态修改配置，但它执行浅合并；更新 `gateway`、`branding` 或 `confirmation` 时应传入完整子对象。语言/主题仍优先用 `setKokoAppearance`。
+
+## 单次任务覆盖项
+
+```tsx
+await getKokoAgent().runGoal('打开设置', {
+  locale: 'zh-CN',
+  localRetries: 3,
+  userGateTimeoutMs: 300_000,
+  onAskUser: question => showHostQuestion(question),
+  onNarration: text => setHint(text),
+});
+```
+
+| 配置 | 默认值 | 说明 |
+|---|---:|---|
+| `baseUrl` / `tokenProvider` / `token` / `appId` | 继承 `config.gateway` | 仅覆盖本次任务的网关配置。 |
+| `locale` | 当前有效语言 | 本次规划请求语言。 |
+| `localRetries` | `3` | 只读 `dump/find` 的本地失败重试次数，范围 `0–3`；触摸、输入等写操作不会自动重放。 |
+| `userGateTimeoutMs` | `300000` | 等待用户完成密码/助记词/授权等本地门禁的最长时间。 |
+| `onAskUser` | 内置追问弹窗 | Agent 需要用户补充信息时的宿主回调。 |
+| `onNarration` | — | 接收当前任务提示/旁白。 |
+
+`resumedFromReload` 和 `resumes` 是 SDK 恢复机制内部字段，宿主不应主动设置。
+
+## 内置 UI 组件参数
+
+| 组件 | 可配置项 |
+|---|---|
+| `KokoEntryButton` | `label`（默认 `Koko`）、`style`。生产宿主更推荐自绘入口并调用 `openKokoChat()`。 |
+| `KokoComposer` | `placeholder`、`disabled`（默认 `false`）。 |
+| `KokoObserver` | `cursor`（默认 `true`）、已废弃的 `composerPlaceholder`。通常由 Provider 自动挂载。 |
+| `KokoOverlayLayer` | `style`、`pointerEvents`（默认 `box-none`）、`testID`。供自定义 SDK 浮层使用。 |
+
+## 低级操作参数
+
+这些 API 主要用于自定义集成；普通宿主不需要直接调用。
+
+| 类型 | 可配置项及默认行为 |
+|---|---|
+| `DumpOptions` | `maxDepth`、`skipInvisible`、`silent`。未传时继承 Agent 配置。 |
+| `TapOptions` | `revealIfNeeded`、`silent`、`cursorDurationMs`。任务规划器会自行决定何时滚动寻找目标。 |
+| `SwipeOptions` | `durationMs`、`silent`。 |
+| `PinchOptions` | `durationMs`（默认 `280`）、`silent`。 |
+| `TypeOptions` | `clear`、`silent`。 |
+
+完整隐私边界见[隐私说明](PRIVACY.zh-CN.md)，三端鉴权见[后端鉴权 Demo](BACKEND_AUTH_DEMOS.zh-CN.md)。
+

package/docs/INTEGRATION.md

@@ -8,14 +8,14 @@ For React Native host apps. After installing the package you must link native co
 
 - 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)
+- An Intent Computing console app with its one-time `clientId` and `clientSecret`; keep the secret on the host backend only
 
 ## 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`
+4. Exchange credentials on the host backend and provide short-lived tokens to `KokoProvider`
 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.**
@@ -65,11 +65,15 @@ Wrap at the app root (or outermost navigation shell):
 import { KokoProvider } from '@intentcomputing/koko-agent-sdk';
 
 export default function App() {
+  const tokenProvider = React.useCallback(async () => {
+    const response = await hostApi.get('/koko/access-token');
+    return response.data as { accessToken: string; expiresAt: number };
+  }, []);
   return (
     <KokoProvider
       config={{
         gateway: {
-          token: 'YOUR_APP_TOKEN',
+          tokenProvider,
           // Default: https://sdk.intentcomputing.net
           // China: https://sdk.intentcomputing.cn
           // baseUrl: 'https://sdk.intentcomputing.cn',
@@ -85,9 +89,11 @@ export default function App() {
 }
 ```
 
+`tokenProvider` calls your backend, never Koko's exchange endpoint directly: the `clientSecret` must not enter the app. The SDK caches credentials using `expiresAt` or JWT `exp` and refreshes once after a 401. See the [backend demos](BACKEND_AUTH_DEMOS.md) for complete examples. Static `gateway.token` remains available only for local development and migration.
+
 `KokoProvider` will:
 
-- Initialize the agent with `gateway.token`
+- Initialize the agent with `gateway.tokenProvider`
 - Mount cursor, progress, and chat sheet (optional — see below)
 
 Open chat from host UI:
@@ -101,6 +107,8 @@ getKokoAgent().openChat();
 
 ### Optional props / config
 
+The table below is only the common subset. See the [complete configuration reference](CONFIGURATION.md) for every Provider, Agent, gateway, branding, runtime, per-run, and built-in component option.
+
 | Key | Purpose | Default |
 |--|--|--|
 | `cursor` | Action cursor overlay | `true` |
@@ -138,7 +146,7 @@ For custom private UIs, declare the gate before navigation or reveal and keep it
 
 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.
+3. Check that requests use the selected official gateway and a short-lived token bound to this app. Do not bundle a client secret, long-lived token or LLM API key. Validate privacy gates and outbound payloads using synthetic data.
 
 ---
 
@@ -157,7 +165,7 @@ Not supported. Use a Dev Client, bare RN, or a production host binary.
 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.
+Your backend exchanges its server-only Intent Computing client credentials for a short-lived token. It is not a model-vendor API key.
 
 ---
 
@@ -166,3 +174,4 @@ Intent Computing console / commercial onboarding — not a model-vendor API key.
 - Package overview: [../README.md](../README.md)
 - npm publish: [PUBLISH.md](./PUBLISH.md)
 - 中文接入指南: [INTEGRATION.zh-CN.md](./INTEGRATION.zh-CN.md)
+- Backend authentication demos: [BACKEND_AUTH_DEMOS.md](./BACKEND_AUTH_DEMOS.md)

package/docs/INTEGRATION.zh-CN.md

@@ -8,14 +8,14 @@
 
 - React Native ≥ 0.73（或 Expo Dev Client / `expo prebuild`，**不支持 Expo Go**）
 - iOS 部署目标 ≥ 15；需本机可 `pod install`
-- 从 Intent Computing 拿到 **应用 token**（`gateway.token`，不是 DeepSeek / OpenAI Key）
+- 在 Intent Computing 用户后台创建应用并取得一次性显示的 `clientId` / `clientSecret`；`clientSecret` 只放宿主后端
 
 ## 步骤一览
 
 1. 安装 npm 包
 2. iOS `pod install`（Android 一般靠 autolinking）
 3. **重新编译原生**（Debug / Release 均可）
-4. 根组件包一层 `KokoProvider` 并配置 token
+4. 宿主后端换取短期 token，App 用 `tokenProvider` 提供给 `KokoProvider`
 5. 将 `openKokoChat()` 对接宿主入口，再发自然语言任务
 
 之后若只改 JS 配置或升级包的纯 JS 部分，Metro 热更新即可；**SDK 含原生改动或首次接入，必须再编原生。**
@@ -63,11 +63,15 @@ npx react-native run-android
 import { KokoProvider } from '@intentcomputing/koko-agent-sdk';
 
 export default function App() {
+  const tokenProvider = React.useCallback(async () => {
+    const response = await hostApi.get('/koko/access-token');
+    return response.data as { accessToken: string; expiresAt: number };
+  }, []);
   return (
     <KokoProvider
       config={{
         gateway: {
-          token: 'YOUR_APP_TOKEN',
+          tokenProvider,
           // 默认 https://sdk.intentcomputing.net（OpenAI）
           // 国内：https://sdk.intentcomputing.cn（DeepSeek）
           baseUrl: 'https://sdk.intentcomputing.cn',
@@ -82,6 +86,8 @@ export default function App() {
 }
 ```
 
+`tokenProvider` 应调用宿主后端，不能直接调用 Koko 换 token 接口，因为 `clientSecret` 绝不能进入 App。SDK 会按 `expiresAt` 或 JWT `exp` 缓存凭证，并在 401 后刷新一次。宿主后端完整实现见[六种主流语言 Demo](BACKEND_AUTH_DEMOS.zh-CN.md)。`gateway.token` 仅保留给本地开发和迁移，不建议用于正式包。
+
 宿主也可主动打开会话：
 
 ```tsx
@@ -92,6 +98,8 @@ getKokoAgent().openChat();
 
 ### 可选开关
 
+下表仅列常用项。Provider、Agent、网关、品牌、运行时、单次任务及内置组件的所有选项见 [SDK 完整配置参考](CONFIGURATION.zh-CN.md)。
+
 | prop / config | 含义 | 默认 |
 |--|--|--|
 | `cursor` | 操作光标 | `true` |
@@ -113,7 +121,7 @@ getKokoAgent().openChat();
 
 1. 启动 App，通过接有 `openKokoChat()` 的宿主按钮打开助手；Provider 不会自动创建宿主入口。
 2. 输入可核验目标，应看到 dump → tap 与光标。
-3. 请求打到官网网关（或 `baseUrl`），App 内无任何 LLM API Key。
+3. 请求打到官网网关（或 `baseUrl`），App 内无 `clientSecret`、长期 token 或任何 LLM API Key。
 
 ---
 
@@ -138,3 +146,4 @@ getKokoAgent().openChat();
 - 英文总览：[../README.md](../README.md)
 - 中文总览：[../README.zh-CN.md](../README.zh-CN.md)
 - 发布：[PUBLISH.zh-CN.md](./PUBLISH.zh-CN.md)
+- 后端鉴权 Demo：[BACKEND_AUTH_DEMOS.zh-CN.md](./BACKEND_AUTH_DEMOS.zh-CN.md)

package/lib/commonjs/KokoAgent.js

@@ -29,8 +29,7 @@ var _ExecutionGuard = require("./commercial/ExecutionGuard.js");
 var _AgentDebug = require("./commercial/AgentDebug.js");
 var _index = require("./i18n/index.js");
 var _ocrTarget = require("./assist/ocrTarget.js");
-var cache;
-function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var r, c, a = Object.defineProperty, n = { __proto__: null, default: e }; if (Object(e) !== e) return n; if (cache || "function" != typeof WeakMap || (cache = new WeakMap()), cache) { if (cache.has(e)) return cache.get(e); cache.set(e, n); } for (c in e) "default" !== c && {}.hasOwnProperty.call(e, c) && ((r = a && Object.getOwnPropertyDescriptor(e, c)) && (r.get || r.set) ? a(n, c, r) : n[c] = e[c]); return n; }
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
  * Koko Agent SDK runtime — dump / find / tap / swipe / pinch / type + cursor + confirm gate + task log.
  */
@@ -173,14 +172,18 @@ class KokoAgent {
     if (this.activeSession || this.claimingCheckpoint) {
       throw new Error((0, _index.runtimeText)('runtime.alreadyRunning', undefined, this.config?.locale));
     }
-    const token = opts?.token ?? this.config.gateway?.token;
-    if (!token) {
+    const gateway = {
+      token: opts?.token ?? this.config.gateway?.token,
+      tokenProvider: opts?.tokenProvider ?? this.config.gateway?.tokenProvider,
+      appId: opts?.appId ?? this.config.gateway?.appId
+    };
+    if (!gateway.token && !gateway.tokenProvider) {
       throw new Error(this.text('runtime.missingToken'));
     }
     const baseUrl = opts?.baseUrl ?? this.config.gateway?.baseUrl;
     const locale = (0, _index.gatewayLocale)((0, _index.currentLocale)(opts?.locale ?? this.config.locale));
     void _AccountStore.AccountStore.refresh({
-      token,
+      ...gateway,
       baseUrl
     });
     const session = this.createSession({
@@ -191,7 +194,7 @@ class KokoAgent {
       onAskUser: opts?.onAskUser,
       onNarration: opts?.onNarration,
       baseUrl,
-      token
+      ...gateway
     });
     this.activeSession = session;
     // An action can take down the context running it (locale/theme/RTL change,
@@ -206,7 +209,7 @@ class KokoAgent {
       await _RunCheckpoint.RunCheckpoint.clear().catch(() => {});
       if (this.activeSession === session) this.activeSession = null;
       void _AccountStore.AccountStore.refresh({
-        token,
+        ...gateway,
         baseUrl
       });
     }
@@ -263,11 +266,10 @@ class KokoAgent {
 
   /** Refresh plan / quota / entitlements from gateway. */
   async refreshAccount() {
-    const token = this.config.gateway?.token;
-    if (!token) return null;
+    const gateway = this.config.gateway;
+    if (!gateway?.token && !gateway?.tokenProvider) return null;
     return _AccountStore.AccountStore.refresh({
-      token,
-      baseUrl: this.config.gateway?.baseUrl
+      ...gateway
     });
   }
   getAccount() {