@intentcomputing/koko-agent-sdk 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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.
+- Add host-backend token exchange documentation and Node.js, Java, Go, Python, PHP and C# examples.
+- Keep static app tokens as a documented legacy development/migration path.
+
 ## 1.0.1
 
 - Clarify npm setup, host-provided entry controls, regional gateways, and privacy responsibilities in the published documentation.

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+React Native SDK for an observable in-app assistant. The host supplies a short-lived access 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)
 
@@ -8,7 +8,7 @@ React Native SDK for an observable in-app assistant. The host supplies an app to
 
 - 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.
+- A host backend that exchanges its server-only client secret for short-lived mobile access tokens. Neither credential is an OpenAI or DeepSeek API key.
 
 ## Install
 
@@ -21,7 +21,7 @@ Rebuild and reinstall the native app after installation or a native SDK upgrade.
 
 ## 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.
+Mount the provider around the host navigation tree and connect `openKokoChat()` to a host button. Supply short-lived credentials through `tokenProvider`.
 
 ```tsx
 import React from 'react';
@@ -29,8 +29,15 @@ import { Button, View } from 'react-native';
 import { KokoProvider, openKokoChat } from '@intentcomputing/koko-agent-sdk';
 
 export default function App() {
+  const getKokoToken = React.useCallback(async () => {
+    const response = await fetch('https://api.your-app.example/koko/access-token', {
+      headers: { Authorization: `Bearer ${await getHostSessionToken()}` },
+    });
+    if (!response.ok) throw new Error(`Koko token ${response.status}`);
+    return response.json(); // { accessToken, expiresAt } (Unix milliseconds)
+  }, []);
   return (
-    <KokoProvider config={{ gateway: { token: 'YOUR_APP_TOKEN' }, locale: 'en' }}>
+    <KokoProvider config={{ gateway: { tokenProvider: getKokoToken }, locale: 'en' }}>
       <View style={{ flex: 1 }}>
         {/* Your app and navigation go here. */}
         <Button title="Open assistant" onPress={() => openKokoChat()} />
@@ -40,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). Use a token valid for the chosen environment. Provider API keys stay on the gateway and must not be bundled into the 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 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

@@ -2,13 +2,13 @@
 
 面向 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)
+[npm 包](https://www.npmjs.com/package/@intentcomputing/koko-agent-sdk) · [English](README.md) · [接入指南](docs/INTEGRATION.zh-CN.md) · [后端鉴权 Demo](docs/BACKEND_AUTH_DEMOS.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 密钥。
+- 生产环境需要宿主后端：长期 `clientSecret` 只保存在后端，App 仅取得短期 access token。它们都不是模型 API 密钥。
 
 ## 安装
 
@@ -27,9 +27,16 @@ import { Button, View } from 'react-native';
 import { KokoProvider, openKokoChat } from '@intentcomputing/koko-agent-sdk';
 
 export default function App() {
+  const getKokoToken = React.useCallback(async () => {
+    const response = await fetch('https://api.your-app.example/koko/access-token', {
+      headers: { Authorization: `Bearer ${await getHostSessionToken()}` },
+    });
+    if (!response.ok) throw new Error(`Koko token ${response.status}`);
+    return response.json(); // { accessToken, expiresAt }；expiresAt 为 Unix 毫秒
+  }, []);
   return (
     <KokoProvider config={{
-      gateway: { token: 'YOUR_APP_TOKEN', baseUrl: 'https://sdk.intentcomputing.cn' },
+      gateway: { tokenProvider: getKokoToken, baseUrl: 'https://sdk.intentcomputing.cn' },
       locale: 'zh',
     }}>
       <View style={{ flex: 1 }}>
@@ -41,7 +48,9 @@ export default function App() {
 }
 ```
 
-默认网关为海外的 `https://sdk.intentcomputing.net`（OpenAI）；国内请显式选择 `https://sdk.intentcomputing.cn`（DeepSeek）。使用对应环境的应用 token，模型 API 密钥只保留在网关。语言或主题变化时调用 `setKokoAppearance({ locale, theme })`；品牌配置通过 `config.branding` 传入，并受应用权益控制。
+默认网关为海外的 `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

@@ -0,0 +1,42 @@
+# Host-backend authentication demos
+
+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
+Host app --short token-----------------------------------> Koko /v1/agent/*
+```
+
+## Rules
+
+- Store `KOKO_CLIENT_SECRET` only in the host backend's secret manager or environment. Never return it to the app or place it in Git or logs.
+- Protect and rate-limit the host `/koko/access-token` endpoint with the host's existing authentication.
+- Derive `subject` on the server from the authenticated user. Send a stable pseudonymous value such as `HMAC-SHA256(hostUserId, separateSalt)`, never an email, phone number, wallet address or advertising ID.
+- Use `https://sdk.intentcomputing.cn` for China and `https://sdk.intentcomputing.net` globally. Credentials and access tokens are region-bound.
+- Koko returns `access_token`, `expires_in`, and `expires_at` (Unix seconds). Return `{ accessToken, expiresAt }` to the SDK, with `expiresAt` expressed in Unix milliseconds.
+- Use a short timeout. Do not log authorization headers or response tokens. Rotate long-lived client secrets.
+
+Complete, copyable examples for **Node.js/TypeScript (Express), Java (Spring Boot), Go, Python (FastAPI), PHP (Laravel), and C# (ASP.NET Core)** are maintained in the [Chinese guide](BACKEND_AUTH_DEMOS.zh-CN.md); all examples use standard HTTP Basic authentication for the server-to-server exchange and derive the subject from the host-authenticated user.
+
+## React Native
+
+```tsx
+const tokenProvider = React.useCallback(async () => {
+  const response = await hostApi.get('/koko/access-token');
+  return response.data as { accessToken: string; expiresAt: number };
+}, []);
+
+<KokoProvider config={{
+  gateway: {
+    baseUrl: 'https://sdk.intentcomputing.net',
+    tokenProvider,
+  },
+}}>{children}</KokoProvider>
+```
+
+Do not persist the access token in AsyncStorage or send it to logs/analytics. The SDK keeps it in memory, refreshes shortly before expiry, and clears it before one forced `tokenProvider` retry after a 401.

package/docs/BACKEND_AUTH_DEMOS.zh-CN.md

@@ -0,0 +1,191 @@
+# 宿主后端鉴权与多语言 Demo
+
+生产环境采用三端通信：宿主 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
+宿主 App ──短期 token──> Koko /v1/agent/*
+```
+
+## 安全约定
+
+- `KOKO_CLIENT_SECRET` 只能放在宿主后端的密钥系统或环境变量中，不能进入 App、Git、日志或前端响应。
+- 宿主的 `/koko/access-token` 必须验证已有登录态并限流，不能做成匿名转发接口。
+- `subject` 必须由后端根据已认证用户生成稳定的匿名值；不要发送邮箱、手机号、钱包地址或设备广告 ID。建议 `HMAC-SHA256(宿主用户ID, 独立盐)`。
+- 国内使用 `https://sdk.intentcomputing.cn`，海外使用 `https://sdk.intentcomputing.net`；凭证和 token 不跨区域使用。
+- Koko 返回字段为 `access_token`、`expires_in`、`expires_at`（Unix 秒）。宿主接口应转换为 SDK 接受的 `{ accessToken, expiresAt }`，其中 `expiresAt` 是 Unix 毫秒。
+- 请求 Koko 必须设置短超时，不记录 Authorization 头或响应 token。长期凭证应定期轮换。
+
+以下示例中的 `authenticatedUserId` 必须来自宿主已经验证的 session/JWT，不得从请求 body 或 query 直接采用。
+
+## Node.js / TypeScript（Express）
+
+```ts
+import crypto from 'node:crypto';
+import express from 'express';
+
+const app = express();
+const gateway = process.env.KOKO_REGION === 'cn'
+  ? 'https://sdk.intentcomputing.cn'
+  : 'https://sdk.intentcomputing.net';
+
+app.get('/koko/access-token', requireHostLogin, async (req, res) => {
+  const subject = crypto.createHmac('sha256', process.env.KOKO_SUBJECT_SALT!)
+    .update(req.user.id) // 只取服务端认证结果
+    .digest('hex');
+  const basic = Buffer.from(
+    `${process.env.KOKO_CLIENT_ID}:${process.env.KOKO_CLIENT_SECRET}`,
+  ).toString('base64');
+  const upstream = await fetch(`${gateway}/v1/sdk/token`, {
+    method: 'POST',
+    headers: { Authorization: `Basic ${basic}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ app_id: process.env.KOKO_APP_ID, subject }),
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!upstream.ok) return res.status(502).json({ error: 'koko_token_unavailable' });
+  const token = await upstream.json();
+  res.set('Cache-Control', 'no-store').json({
+    accessToken: token.access_token,
+    expiresAt: token.expires_at * 1000,
+  });
+});
+```
+
+## Java（Spring Boot 3）
+
+```java
+record KokoToken(String access_token, long expires_at) {}
+record AppToken(String accessToken, long expiresAt) {}
+
+AppToken exchange(String authenticatedUserId) throws Exception {
+  String subject = hmacSha256Hex(System.getenv("KOKO_SUBJECT_SALT"), authenticatedUserId);
+  String basic = Base64.getEncoder().encodeToString(
+      (System.getenv("KOKO_CLIENT_ID") + ":" + System.getenv("KOKO_CLIENT_SECRET"))
+          .getBytes(StandardCharsets.UTF_8));
+  String body = objectMapper.writeValueAsString(Map.of(
+      "app_id", System.getenv("KOKO_APP_ID"), "subject", subject));
+  HttpRequest request = HttpRequest.newBuilder(URI.create(kokoGateway + "/v1/sdk/token"))
+      .timeout(Duration.ofSeconds(5)).header("Authorization", "Basic " + basic)
+      .header("Content-Type", "application/json")
+      .POST(HttpRequest.BodyPublishers.ofString(body)).build();
+  HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
+  if (response.statusCode() != 200) throw new IllegalStateException("Koko token unavailable");
+  KokoToken token = objectMapper.readValue(response.body(), KokoToken.class);
+  return new AppToken(token.access_token(), token.expires_at() * 1000L);
+}
+```
+
+Spring Controller 必须从 `Principal` / SecurityContext 取得 `authenticatedUserId`，并返回 `Cache-Control: no-store`。
+
+## Go（net/http）
+
+```go
+func exchangeKokoToken(ctx context.Context, authenticatedUserID string) (string, int64, error) {
+    mac := hmac.New(sha256.New, []byte(os.Getenv("KOKO_SUBJECT_SALT")))
+    mac.Write([]byte(authenticatedUserID))
+    body, _ := json.Marshal(map[string]string{
+        "app_id": os.Getenv("KOKO_APP_ID"), "subject": hex.EncodeToString(mac.Sum(nil)),
+    })
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second); defer cancel()
+    req, _ := http.NewRequestWithContext(ctx, http.MethodPost, kokoGateway+"/v1/sdk/token", bytes.NewReader(body))
+    req.SetBasicAuth(os.Getenv("KOKO_CLIENT_ID"), os.Getenv("KOKO_CLIENT_SECRET"))
+    req.Header.Set("Content-Type", "application/json")
+    resp, err := http.DefaultClient.Do(req); if err != nil { return "", 0, err }
+    defer resp.Body.Close()
+    if resp.StatusCode != http.StatusOK { return "", 0, fmt.Errorf("koko token: %s", resp.Status) }
+    var out struct { AccessToken string `json:"access_token"`; ExpiresAt int64 `json:"expires_at"` }
+    if err := json.NewDecoder(resp.Body).Decode(&out); err != nil { return "", 0, err }
+    return out.AccessToken, out.ExpiresAt * 1000, nil
+}
+```
+
+## Python（FastAPI + HTTPX）
+
+```python
+import hashlib, hmac, os
+import httpx
+from fastapi import Depends, HTTPException, Response
+
+@app.get('/koko/access-token')
+async def koko_token(response: Response, user=Depends(require_host_user)):
+    subject = hmac.new(os.environ['KOKO_SUBJECT_SALT'].encode(), str(user.id).encode(), hashlib.sha256).hexdigest()
+    async with httpx.AsyncClient(timeout=5.0) as client:
+        upstream = await client.post(
+            f'{KOKO_GATEWAY}/v1/sdk/token',
+            auth=(os.environ['KOKO_CLIENT_ID'], os.environ['KOKO_CLIENT_SECRET']),
+            json={'app_id': os.environ['KOKO_APP_ID'], 'subject': subject},
+        )
+    if upstream.status_code != 200:
+        raise HTTPException(502, 'Koko token unavailable')
+    token = upstream.json()
+    response.headers['Cache-Control'] = 'no-store'
+    return {'accessToken': token['access_token'], 'expiresAt': token['expires_at'] * 1000}
+```
+
+## PHP（Laravel）
+
+```php
+public function token(Request $request): JsonResponse
+{
+    $userId = (string) $request->user()->getAuthIdentifier(); // auth middleware 已验证
+    $subject = hash_hmac('sha256', $userId, env('KOKO_SUBJECT_SALT'));
+    $upstream = Http::timeout(5)
+        ->withBasicAuth(env('KOKO_CLIENT_ID'), env('KOKO_CLIENT_SECRET'))
+        ->post(config('services.koko.gateway').'/v1/sdk/token', [
+            'app_id' => env('KOKO_APP_ID'), 'subject' => $subject,
+        ]);
+    abort_unless($upstream->successful(), 502, 'Koko token unavailable');
+    return response()->json([
+        'accessToken' => $upstream['access_token'],
+        'expiresAt' => $upstream['expires_at'] * 1000,
+    ])->header('Cache-Control', 'no-store');
+}
+```
+
+## C#（ASP.NET Core）
+
+```csharp
+app.MapGet("/koko/access-token", async (ClaimsPrincipal user, IHttpClientFactory factory) => {
+    var userId = user.FindFirstValue(ClaimTypes.NameIdentifier)
+        ?? throw new UnauthorizedAccessException();
+    var subject = Convert.ToHexString(HMACSHA256.HashData(
+        Encoding.UTF8.GetBytes(Environment.GetEnvironmentVariable("KOKO_SUBJECT_SALT")!),
+        Encoding.UTF8.GetBytes(userId))).ToLowerInvariant();
+    var clientId = Environment.GetEnvironmentVariable("KOKO_CLIENT_ID")!;
+    var clientSecret = Environment.GetEnvironmentVariable("KOKO_CLIENT_SECRET")!;
+    var appId = Environment.GetEnvironmentVariable("KOKO_APP_ID")!;
+    var request = new HttpRequestMessage(HttpMethod.Post, $"{kokoGateway}/v1/sdk/token");
+    var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(
+        $"{clientId}:{clientSecret}"));
+    request.Headers.Authorization = new("Basic", credentials);
+    request.Content = JsonContent.Create(new { app_id = appId, subject });
+    var upstream = await factory.CreateClient("koko").SendAsync(request);
+    if (!upstream.IsSuccessStatusCode) return Results.Problem(statusCode: 502, title: "Koko token unavailable");
+    var token = await upstream.Content.ReadFromJsonAsync<KokoToken>();
+    return Results.Json(new { accessToken = token!.access_token, expiresAt = token.expires_at * 1000 },
+        headers: new Dictionary<string, string> { ["Cache-Control"] = "no-store" });
+}).RequireAuthorization();
+```
+
+## App 端
+
+```tsx
+const tokenProvider = React.useCallback(async () => {
+  const response = await hostApi.get('/koko/access-token');
+  return response.data as { accessToken: string; expiresAt: number };
+}, []);
+
+<KokoProvider config={{
+  gateway: {
+    baseUrl: 'https://sdk.intentcomputing.cn',
+    tokenProvider,
+  },
+}}>{children}</KokoProvider>
+```
+
+不要把 token 写入 AsyncStorage、日志或分析事件。SDK 自己在内存中缓存，到期前刷新；如果网关返回 401，会清除缓存并强制调用一次 `tokenProvider`。

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.
+