@intentcomputing/koko-agent-sdk 1.1.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.1.1
+
+- Add complete English and Chinese configuration references covering Provider, Agent, gateway, branding, runtime appearance, per-run overrides, and built-in UI options.
+- Clarify that short-lived access tokens stay in memory and refresh lazily on requests near expiry.
+
 ## 1.1.0
 
 - Add production `tokenProvider` authentication with expiry-aware caching and one forced refresh after a 401.

package/README.md

@@ -47,9 +47,9 @@ export default function App() {
 }
 ```
 
-The default gateway is `https://sdk.intentcomputing.net` (OpenAI). For China, set `gateway.baseUrl` to `https://sdk.intentcomputing.cn` (DeepSeek). The SDK caches short-lived tokens, refreshes before expiry, and retries once after a 401. Long-lived client secrets and model-provider keys must never be bundled into the app. See the [backend authentication demos](docs/BACKEND_AUTH_DEMOS.md) for Node.js, Java, Go, Python, PHP and C#.
+The default gateway is `https://sdk.intentcomputing.net` (OpenAI). For China, set `gateway.baseUrl` to `https://sdk.intentcomputing.cn` (DeepSeek). The SDK caches short-lived tokens in memory, refreshes lazily when a request occurs near expiry, and retries once after a 401. Long-lived client secrets and model-provider keys must never be bundled into the app. See the [backend authentication demos](docs/BACKEND_AUTH_DEMOS.md) for Node.js, Java, Go, Python, PHP and C#.
 
-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.
+Call `setKokoAppearance({ locale, theme })` when host preferences change. Configure branding through `config.branding`; custom branding is subject to the app's entitlement. See the [complete configuration reference](docs/CONFIGURATION.md) for every Provider, Agent, gateway, runtime, and per-run option, and the [integration guide](docs/INTEGRATION.md) for host actions, privacy gates, and lifecycle details.
 
 ## Privacy and limits
 

package/README.zh-CN.md

@@ -48,7 +48,9 @@ export default function App() {
 }
 ```
 
-默认网关为海外的 `https://sdk.intentcomputing.net`（OpenAI）；国内请显式选择 `https://sdk.intentcomputing.cn`（DeepSeek）。SDK 会缓存短期 token、在过期前刷新，并在 401 后强制刷新一次。长期 `clientSecret` 和模型 API 密钥都不得进入 App。完整三端流程及 Node.js、Java、Go、Python、PHP、C# Demo 见[后端鉴权 Demo](docs/BACKEND_AUTH_DEMOS.zh-CN.md)。
+默认网关为海外的 `https://sdk.intentcomputing.net`（OpenAI）；国内请显式选择 `https://sdk.intentcomputing.cn`（DeepSeek）。SDK 仅在内存缓存短期 token；当一次请求发生且 token 临近过期时才按需刷新，401 后强制刷新并重试一次。长期 `clientSecret` 和模型 API 密钥都不得进入 App。完整三端流程及 Node.js、Java、Go、Python、PHP、C# Demo 见[后端鉴权 Demo](docs/BACKEND_AUTH_DEMOS.zh-CN.md)。
+
+Provider、Agent、网关、品牌、运行时和单次任务的全部选项见 [SDK 完整配置参考](docs/CONFIGURATION.zh-CN.md)。
 
 宿主必须在展示密码、私钥、助记词及其验证页面前设置隐私标记和用户操作门禁，由用户亲自完成敏感步骤。脱敏的页面信息和任务上下文会发送到所选网关进行规划，接入方应使用虚构数据验证隐私边界。详见[隐私说明](docs/PRIVACY.zh-CN.md)。
 

package/docs/BACKEND_AUTH_DEMOS.md

@@ -2,6 +2,10 @@
 
 Production authentication uses three parties: the mobile app authenticates to its existing host backend; the host backend exchanges its server-only `clientId` and `clientSecret` with Koko; the app receives a 5–15 minute access token for the SDK.
 
+Each `clientId` may optionally be restricted to exact host-backend egress IPs. Multiple IPv4/IPv6 addresses are comma-separated; omitting the allowlist leaves IP unrestricted. This is defense in depth and does not replace the client secret.
+
+Creating an app in the Intent Computing console now issues the `clientId` and one-time `clientSecret`. The Apps / Server credentials page manages IPs, status, and secret rotation; admins can also manage regions and review the audit trail. Only a secret hash is stored. Legacy API keys remain migration-only.
+
 ```text
 Host app --host session--> Host backend --client secret--> Koko /v1/sdk/token
 Host app <--short token--- Host backend <--short token---- Koko

package/docs/BACKEND_AUTH_DEMOS.zh-CN.md

@@ -2,6 +2,10 @@
 
 生产环境采用三端通信：宿主 App 通过自己的登录态请求宿主后端；宿主后端使用仅存于服务器的 `clientId` / `clientSecret` 向 Koko 换取 5～15 分钟的 access token；App 再把短期 token 交给 SDK。
 
+Koko 可为每个 `clientId` 选配宿主后端出口 IP 白名单。多个精确 IPv4/IPv6 地址用逗号分隔；不配置时不限制。启用后，请把宿主后端所有稳定 NAT 出口地址提供给 Intent Computing。IP 白名单是 `clientSecret` 之外的附加约束，不能替代密钥认证。
+
+在 Intent Computing 用户后台创建应用时，会自动生成 `clientId` / `clientSecret`。完整 Secret 仅显示一次；之后可在“应用 / 服务端凭证”中维护 IP、启停或轮换 Secret。管理员后台可调整状态、授权区域和 IP，并查看操作审计。Secret 只保存哈希，旧 API Key 仅用于迁移兼容。
+
 ```text
 宿主 App ──宿主登录态──> 宿主后端 ──clientSecret──> Koko /v1/sdk/token
 宿主 App <──短期 token── 宿主后端 <──短期 token── Koko

package/docs/CONFIGURATION.md

@@ -0,0 +1,188 @@
+# Complete SDK configuration reference
+
+> 中文版：[CONFIGURATION.zh-CN.md](./CONFIGURATION.zh-CN.md)
+
+This reference covers the public host configuration surfaces: `KokoProvider`, `KokoAgentConfig`, runtime appearance, per-run overrides, and built-in UI components. The exported TypeScript types remain the source of truth.
+
+## Complete example
+
+```tsx
+import React from 'react';
+import { KokoProvider } 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.net',
+          tokenProvider,
+          // appId normally comes from the native Bundle ID / Package Name.
+        },
+        locale: 'en',
+        theme: 'light', // The host theme; Koko chrome uses the contrasting theme.
+        branding: {
+          name: 'My Assistant',
+          tagline: 'Control this app with natural language',
+          placeholder: 'Tell me what you want to do…',
+          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
+
+| Option | Type | Default | Purpose |
+|---|---|---:|---|
+| `children` | `ReactNode` | Required | Host app or outer navigation tree. |
+| `config` | `KokoAgentConfig` | `{}` | Agent, gateway, branding, and confirmation configuration. |
+| `cursor` | `boolean` | `true` | Show the observable action cursor. |
+| `observer` | `boolean` | Inherits `config.observer` | Mount progress and chat UI; an explicit prop wins. |
+| `dialogs` | `boolean` | `true` | Mount built-in confirm and ask-user dialogs. Provide host callbacks if disabled. |
+| `resumeAfterReload` | `boolean` | `true` | Resume one recent goal after a JS-context reload caused by host locale/theme changes. |
+| `remoteSmokePort` | `number` | `0` | Local development smoke-driver port. Never enable in production. |
+| `composerPlaceholder` | `string` | — | Deprecated; use `config.branding.placeholder`. |
+
+`KokoProvider observer={false}` hides built-in progress/chat UI only. `config.observer={false}` also disables automatic task logging. Keep both enabled for the complete built-in experience.
+
+## `KokoAgentConfig`
+
+| Option | Type | Default | Purpose |
+|---|---|---:|---|
+| `gateway` | `GatewayConfig` | — | Gateway and short-token configuration required for production runs. |
+| `locale` | `'zh' \| 'en'` | `'en'` | Initial built-in UI language. Prefer `setKokoAppearance` for runtime changes. |
+| `theme` | `'light' \| 'dark'` | `'light'` | The **host app's** current theme; Koko chrome uses the opposite theme for contrast. |
+| `branding` | `KokoBrandingConfig` | Koko defaults | Custom name, icon, copy, and accent; requires the `custom_branding` entitlement. |
+| `confirmation` | `ConfirmationPolicy` | Confirm, `preflight` | Human confirmation policy for high-risk goals. |
+| `onConfirmSensitive` | `(ctx) => Promise<boolean>` | Built-in dialog | Custom sensitive-action confirmation. Return `true` to proceed. |
+| `webWalletAliases` | `string[]` | `[]` | Verified public labels for the host's own injected wallet. |
+| `dumpMaxDepth` | `number` | `80` | Maximum native accessibility-tree depth. Small values can truncate RN navigation wrappers. |
+| `dumpSkipInvisible` | `boolean` | `true` | Drop invisible nodes from observations. |
+| `cursorDurationMs` | `number` | `480` | Default cursor animation duration in milliseconds. |
+| `observer` | `boolean` | `true` | Enable task logs and, unless overridden by the Provider prop, built-in progress/chat UI. |
+| `debug` | `boolean` | `true` in Metro Debug; `false` in Release | Capability and execution logs only; it never relaxes security. Set `false` explicitly in production. |
+| `devMode` | `boolean` | Same as `debug` | Deprecated alias for `debug`. |
+| `onUsageEvent` | `(event) => void` | — | Non-blocking local analytics/UX notifications; not authoritative for billing. |
+
+### `gateway`
+
+| Option | Type | Default | Purpose |
+|---|---|---:|---|
+| `baseUrl` | `string` | `https://sdk.intentcomputing.net` | Global/OpenAI gateway. Use `https://sdk.intentcomputing.cn` for China/DeepSeek. Release builds accept official hosts only. |
+| `tokenProvider` | `() => Promise<string \| { accessToken; expiresAt? }>` | — | Recommended. Fetches a short token from the **host backend**. The SDK caches it in memory, refreshes lazily on a request near expiry, and refreshes/retries once after a 401. |
+| `token` | `string` | — | Legacy static token for local development and migration only. Never ship it in production. |
+| `appId` | `string` | Native Bundle ID / Package Name | Must match the registered host app; normally no explicit value is needed. |
+
+`expiresAt` is Unix time in **milliseconds**. If omitted, the SDK reads JWT `exp`; if neither exists, it assumes 60 seconds. Never place `clientSecret` or DeepSeek/OpenAI keys in the app.
+
+### `branding`
+
+| Option | Type | Default | Purpose |
+|---|---|---:|---|
+| `name` | `string` | `Koko` | Assistant display name. |
+| `icon` | `number \| { uri: string } \| string` | K mark | Accepts `require()`, an image/Data URI, or a short text mark. |
+| `tagline` | `string` | Localized default | Chat header subtitle. |
+| `placeholder` | `string` | Localized default | Composer placeholder. |
+| `primaryColor` | `string` | SDK accent | Badge and send-button accent using a React Native color string. |
+
+Without the entitlement, the SDK falls back to Koko defaults and emits one `branding_downgraded` usage event.
+
+### `confirmation`
+
+| Option | Type | Default | Purpose |
+|---|---|---:|---|
+| `requireUserConfirm` | `boolean` | `true` | Require confirmation for high-risk goals. |
+| `mode` | `'preflight' \| 'inline' \| 'off'` | `'preflight'` | Confirm once before a run, use legacy inline checks, or disable SDK confirmation. |
+| `sensitivePatterns` | `RegExp[]` | Built-in patterns | Custom high-risk goal rules. A non-empty array replaces the defaults. |
+
+Disabling confirmation does not bypass local password, recovery-phrase, private-key, or OTP gates. The user must still complete those surfaces personally.
+
+### `onUsageEvent` events
+
+Events are `task_started`, `task_finished`, `agent_step`, `quota_exceeded`, `sheet_opened`, `sheet_closed`, and `branding_downgraded`. Do not forward goal text to an analytics provider without user authorization.
+
+## Runtime locale and theme
+
+```tsx
+import { setKokoAppearance } from '@intentcomputing/koko-agent-sdk';
+
+useEffect(() => {
+  setKokoAppearance({ locale: hostLocale, theme: hostTheme });
+}, [hostLocale, hostTheme]);
+```
+
+- Locale strings beginning with `zh` map to Chinese; all others currently map to English.
+- Theme is the host's actual `'light'` or `'dark'` theme.
+- Runtime appearance takes precedence over static `config.locale` and `config.theme`.
+
+`getKokoAgent().configure(patch)` updates configuration at runtime, but performs a shallow merge. Pass complete `gateway`, `branding`, or `confirmation` sub-objects when changing them. Prefer `setKokoAppearance` for locale/theme.
+
+## Per-run overrides
+
+```tsx
+await getKokoAgent().runGoal('Open settings', {
+  locale: 'en-US',
+  localRetries: 3,
+  userGateTimeoutMs: 300_000,
+  onAskUser: question => showHostQuestion(question),
+  onNarration: text => setHint(text),
+});
+```
+
+| Option | Default | Purpose |
+|---|---:|---|
+| `baseUrl` / `tokenProvider` / `token` / `appId` | Inherit `config.gateway` | Override the gateway for this run only. |
+| `locale` | Effective current locale | Planner request locale for this run. |
+| `localRetries` | `3` | Retry count `0–3` for read-only `dump/find` failures. Touches and typing are never automatically replayed. |
+| `userGateTimeoutMs` | `300000` | Maximum wait for the user to finish a password/recovery/authorization gate. |
+| `onAskUser` | Built-in ask dialog | Host callback when the agent needs more information. |
+| `onNarration` | — | Receives current task narration. |
+
+`resumedFromReload` and `resumes` are SDK-internal recovery fields; hosts should not set them.
+
+## Built-in UI component props
+
+| Component | Options |
+|---|---|
+| `KokoEntryButton` | `label` (default `Koko`) and `style`. Production hosts should normally draw their own entry and call `openKokoChat()`. |
+| `KokoComposer` | `placeholder` and `disabled` (default `false`). |
+| `KokoObserver` | `cursor` (default `true`) and deprecated `composerPlaceholder`. Normally mounted by the Provider. |
+| `KokoOverlayLayer` | `style`, `pointerEvents` (default `box-none`), and `testID` for custom SDK chrome. |
+
+## Low-level action options
+
+Most hosts do not call these directly.
+
+| Type | Options and defaults |
+|---|---|
+| `DumpOptions` | `maxDepth`, `skipInvisible`, `silent`; absent values inherit Agent configuration. |
+| `TapOptions` | `revealIfNeeded`, `silent`, `cursorDurationMs`; the planner normally decides when to reveal an offscreen control. |
+| `SwipeOptions` | `durationMs`, `silent`. |
+| `PinchOptions` | `durationMs` (default `280`), `silent`. |
+| `TypeOptions` | `clear`, `silent`. |
+
+See [Privacy](PRIVACY.md) for data boundaries and [backend authentication demos](BACKEND_AUTH_DEMOS.md) for the three-party token flow.
+

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,7 +8,7 @@ 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 Intent Computing `clientId` and `clientSecret`; keep the secret on the host backend only
+- An Intent Computing console app with its one-time `clientId` and `clientSecret`; keep the secret on the host backend only
 
 ## Checklist
 
@@ -107,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` |

package/docs/INTEGRATION.zh-CN.md

@@ -8,7 +8,7 @@
 
 - React Native ≥ 0.73（或 Expo Dev Client / `expo prebuild`，**不支持 Expo Go**）
 - iOS 部署目标 ≥ 15；需本机可 `pod install`
-- 从 Intent Computing 拿到 `clientId` / `clientSecret`；`clientSecret` 只放宿主后端
+- 在 Intent Computing 用户后台创建应用并取得一次性显示的 `clientId` / `clientSecret`；`clientSecret` 只放宿主后端
 
 ## 步骤一览
 
@@ -98,6 +98,8 @@ getKokoAgent().openChat();
 
 ### 可选开关
 
+下表仅列常用项。Provider、Agent、网关、品牌、运行时、单次任务及内置组件的所有选项见 [SDK 完整配置参考](CONFIGURATION.zh-CN.md)。
+
 | prop / config | 含义 | 默认 |
 |--|--|--|
 | `cursor` | 操作光标 | `true` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentcomputing/koko-agent-sdk",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Koko Agent SDK — in-app AI agent for React Native (dump / find / tap with visible cursor). Talk to Intent Computing gateway; no LLM API keys in the app.",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
@@ -39,6 +39,8 @@
     "SECURITY.md",
     "docs/INTEGRATION.md",
     "docs/INTEGRATION.zh-CN.md",
+    "docs/CONFIGURATION.md",
+    "docs/CONFIGURATION.zh-CN.md",
     "docs/PRIVACY.md",
     "docs/PRIVACY.zh-CN.md",
     "docs/BACKEND_AUTH_DEMOS.md",