@intentcomputing/koko-agent-sdk 1.0.1

package/src/commercial/branding.ts

@@ -0,0 +1,97 @@
+import type {
+  KokoAccountSnapshot,
+  KokoBrandingConfig,
+  KokoEntitlements,
+  KokoLocale,
+  KokoUsageEvent,
+} from '../types';
+import { t } from '../i18n';
+
+export const DEFAULT_ENTITLEMENTS: KokoEntitlements = {
+  custom_branding: false,
+  locale: true,
+};
+
+export type ResolvedBranding = {
+  name: string;
+  /** Letter shown when no image icon. */
+  mark: string;
+  /** Image source when host provided a require()/uri icon and entitlement allows. */
+  iconSource: number | { uri: string } | null;
+  tagline: string;
+  placeholder: string;
+  primaryColor: string;
+  /** True when host asked for custom branding but plan denied it. */
+  downgraded: boolean;
+};
+
+const DEFAULT_PRIMARY = '#0A84FF';
+
+function wantsCustomBranding(branding?: KokoBrandingConfig): boolean {
+  if (!branding) return false;
+  return Boolean(
+    (branding.name && branding.name.trim() && branding.name.trim() !== 'Koko') ||
+      branding.icon != null ||
+      (branding.tagline && branding.tagline.trim()) ||
+      (branding.placeholder && branding.placeholder.trim()) ||
+      (branding.primaryColor && branding.primaryColor.trim()),
+  );
+}
+
+/**
+ * Resolve what the **built-in** chat UI may show.
+ * This is a soft client gate for honest hosts + official gateway.
+ * Forked SDKs / custom chrome can always draw their own brand — that is outside
+ * this product surface. Usage metering remains server-authoritative.
+ */
+export function resolveBranding(
+  locale: KokoLocale,
+  branding: KokoBrandingConfig | undefined,
+  entitlements: KokoEntitlements | undefined,
+): ResolvedBranding {
+  const allowed = entitlements?.custom_branding === true;
+  const custom = wantsCustomBranding(branding);
+  const downgraded = custom && !allowed;
+  const useCustom = custom && allowed;
+
+  let iconSource: number | { uri: string } | null = null;
+  let mark = t(locale, 'brand.defaultMark');
+  if (useCustom && branding?.icon != null) {
+    if (typeof branding.icon === 'string') {
+      if (/^https?:\/\//i.test(branding.icon) || branding.icon.startsWith('data:')) {
+        iconSource = { uri: branding.icon };
+      } else {
+        mark = branding.icon.slice(0, 2);
+      }
+    } else {
+      iconSource = branding.icon;
+    }
+  }
+
+  return {
+    name: useCustom && branding?.name?.trim() ? branding.name.trim() : t(locale, 'brand.defaultName'),
+    mark,
+    iconSource,
+    tagline:
+      useCustom && branding?.tagline?.trim()
+        ? branding.tagline.trim()
+        : t(locale, 'brand.defaultTagline'),
+    placeholder:
+      useCustom && branding?.placeholder?.trim()
+        ? branding.placeholder.trim()
+        : t(locale, 'brand.defaultPlaceholder'),
+    primaryColor:
+      useCustom && branding?.primaryColor?.trim()
+        ? branding.primaryColor.trim()
+        : DEFAULT_PRIMARY,
+    downgraded,
+  };
+}
+
+export function emptyAccount(): KokoAccountSnapshot {
+  return {
+    plan: 'free',
+    entitlements: { ...DEFAULT_ENTITLEMENTS },
+    quota: { daily: 30, used_today: 0, remaining: 30 },
+  };
+}

package/src/commercial/devMode.ts

@@ -0,0 +1,48 @@
+import type { KokoAgentConfig } from '../types';
+
+/** True only in Metro debug clients (never in store release binaries). */
+export function isMetroDevBuild(): boolean {
+  try {
+    // eslint-disable-next-line no-undef
+    return typeof __DEV__ !== 'undefined' && __DEV__ === true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Verbose SDK / agent execution logs for developers.
+ * Does NOT relax security (permits, gateway allowlist).
+ *
+ * On when:
+ * - `config.debug === true`, or
+ * - Metro `__DEV__` and `config.debug !== false`
+ *
+ * Release builds: only if host explicitly sets `debug: true`
+ * (logs only — still cannot use localhost gateway or skip permits).
+ */
+export function resolveDebugLogging(
+  config?: Pick<KokoAgentConfig, 'debug' | 'devMode'>,
+): boolean {
+  if (config?.debug === true || config?.devMode === true) return true;
+  if (config?.debug === false || config?.devMode === false) return false;
+  return isMetroDevBuild();
+}
+
+/**
+ * @deprecated Use resolveDebugLogging. Kept for call-site migration.
+ * Previously also meant "relax security" — that behavior is removed.
+ */
+export function resolveDevMode(
+  config?: Pick<KokoAgentConfig, 'debug' | 'devMode'>,
+): boolean {
+  return resolveDebugLogging(config);
+}
+
+/**
+ * Localhost / LAN gateway is only for Intent Computing debugging the
+ * in-repo gateway against a Metro debug app — not a customer "self-host" mode.
+ */
+export function allowLocalGatewayForDebugClient(): boolean {
+  return isMetroDevBuild();
+}

package/src/commercial/trust.ts

@@ -0,0 +1,67 @@
+/**
+ * Gateway host policy + entitlement trust.
+ *
+ * Customers always use official Intent Computing hosts in release apps.
+ * Localhost is allowed only in Metro debug clients (so we can dogfood the
+ * in-repo gateway) — that is NOT a supported "self-host your own AI" mode.
+ */
+
+// `agent.intentcomputing.net` is a different Intent Computing service and must
+// not be trusted as a gateway.
+const OFFICIAL_HOST_SUFFIXES = [
+  'sdk.intentcomputing.cn',
+  'sdk.intentcomputing.net',
+];
+
+export function isLocalDevHost(hostname: string): boolean {
+  const host = hostname.toLowerCase();
+  return (
+    host === 'localhost' ||
+    host === '127.0.0.1' ||
+    host === '10.0.2.2' ||
+    host === '0.0.0.0'
+  );
+}
+
+export function isOfficialGatewayHost(hostname: string): boolean {
+  const host = hostname.toLowerCase();
+  return OFFICIAL_HOST_SUFFIXES.some(
+    (h) => host === h || host.endsWith(`.${h}`),
+  );
+}
+
+/** Hosts whose /v1/me branding claims we trust. */
+export function isTrustedEntitlementHost(baseUrl: string): boolean {
+  try {
+    const u = new URL(baseUrl.includes('://') ? baseUrl : `https://${baseUrl}`);
+    return isOfficialGatewayHost(u.hostname) || isLocalDevHost(u.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param allowLocalLab when true (Metro debug client only), localhost/LAN OK.
+ */
+export function isAllowedGatewayUrl(
+  baseUrl: string,
+  allowLocalLab: boolean,
+): { ok: true } | { ok: false; reason: string } {
+  try {
+    const u = new URL(baseUrl.includes('://') ? baseUrl : `https://${baseUrl}`);
+    if (isOfficialGatewayHost(u.hostname)) return { ok: true };
+    if (allowLocalLab && isLocalDevHost(u.hostname)) return { ok: true };
+    if (allowLocalLab) {
+      const ipv4 = /^\d{1,3}(\.\d{1,3}){3}$/.test(u.hostname);
+      if (ipv4) return { ok: true };
+    }
+    return {
+      ok: false,
+      reason: allowLocalLab
+        ? `unsupported gateway host: ${u.hostname}`
+        : `unsupported gateway host: ${u.hostname}`,
+    };
+  } catch {
+    return { ok: false, reason: 'invalid gateway.baseUrl' };
+  }
+}

package/src/confirmation/gate.ts

@@ -0,0 +1,82 @@
+import type { ConfirmationPolicy, SensitiveConfirmContext } from '../types';
+
+/**
+ * Irreversible / high-risk intents — confirmed once **before** the agent run.
+ * Ordinary list deletes are NOT sensitive.
+ */
+export const DEFAULT_SENSITIVE_PATTERNS: RegExp[] = [
+  /转账|转\s*\d|transfer|withdraw|send\s*(usdt|usdc|eth|btc)?/i,
+  /授权|approve|export\s*(key|seed|mnemonic)|私钥|助记词/i,
+  /删除(钱包|账户|账号|密钥)|永久删除|注销账户|销毁/i,
+  /delete\s*(wallet|account|key|seed)|destroy\s*account/i,
+  /confirm\s*(transfer|payment)|确认(转账|支付|授权)/i,
+];
+
+export function isSensitiveLabel(
+  label: string | undefined,
+  policy?: ConfirmationPolicy,
+): boolean {
+  if (!label) return false;
+  const patterns = policy?.sensitivePatterns?.length
+    ? policy.sensitivePatterns
+    : DEFAULT_SENSITIVE_PATTERNS;
+  return patterns.some((re) => re.test(label));
+}
+
+/** Goal looks like a high-risk operation → preflight confirm. */
+export function isSensitiveGoal(
+  goal: string,
+  policy?: ConfirmationPolicy,
+): boolean {
+  return isSensitiveLabel(goal, policy);
+}
+
+/**
+ * Mid-step gate (legacy). Prefer preflight; during unattended runs this should no-op.
+ */
+export async function runConfirmationGate(
+  ctx: SensitiveConfirmContext,
+  policy: ConfirmationPolicy | undefined,
+  onConfirm?: (ctx: SensitiveConfirmContext) => Promise<boolean>,
+): Promise<boolean> {
+  const mode = policy?.mode ?? 'preflight';
+  if (mode === 'off' || mode === 'preflight') {
+    // Preflight already asked (or disabled). Never block mid-execution.
+    return true;
+  }
+
+  const requireConfirm = policy?.requireUserConfirm !== false;
+  if (!requireConfirm) return true;
+
+  const label = ctx.label ?? ctx.action;
+  if (!isSensitiveLabel(label, policy) && !isSensitiveLabel(ctx.action, policy)) {
+    return true;
+  }
+
+  if (!onConfirm) return false;
+  return onConfirm(ctx);
+}
+
+/**
+ * Ask once before the agent loop. Returns false if user declines.
+ */
+export async function runPreflightConfirm(
+  goal: string,
+  policy: ConfirmationPolicy | undefined,
+  onConfirm?: (ctx: SensitiveConfirmContext) => Promise<boolean>,
+): Promise<boolean> {
+  const mode = policy?.mode ?? 'preflight';
+  if (mode === 'off') return true;
+  if (mode !== 'preflight' && mode !== 'inline') return true;
+
+  const requireConfirm = policy?.requireUserConfirm !== false;
+  if (!requireConfirm) return true;
+  if (!isSensitiveGoal(goal, policy)) return true;
+
+  if (!onConfirm) return false;
+
+  return onConfirm({
+    action: 'preflight',
+    label: goal,
+  });
+}

package/src/cursor/CursorOverlay.tsx

@@ -0,0 +1,138 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { Animated, StyleSheet, View } from 'react-native';
+import { CursorController, type CursorState } from './controller';
+import { useTaskStore } from '../task/useTaskStore';
+import { TaskStore } from '../task/TaskStore';
+import { KOKO_CURSOR_TEST_ID } from '../ui/KokoOverlayLayer';
+import { KokoHostOverlay } from '../ui/hostOverlay';
+import { useOverlayOrigin } from '../ui/useOverlayOrigin';
+import { PointerHand } from './PointerHand';
+import { CURSOR_H, CURSOR_TIP_X, CURSOR_TIP_Y, CURSOR_W } from './pointer';
+
+/**
+ * Native-looking mouse pointer while the agent acts.
+ *
+ * Uses KokoHostOverlay (FullWindowOverlay on iOS when available) so the
+ * cursor stays above react-native-screens Settings / stack modals.
+ *
+ * Only mount while the cursor is actually visible — an empty FullWindowOverlay
+ * stacked under KokoObserver can steal the top presentation and hide the
+ * progress pill during host.run-only assist paths.
+ */
+export function CursorOverlay() {
+  const [state, setState] = useState<CursorState>(CursorController.getState());
+  const { tasks, activeTaskId, ui } = useTaskStore();
+  const running = tasks.some(
+    (t) => t.id === activeTaskId && t.status === 'running',
+  );
+  const anim = useRef(new Animated.ValueXY({ x: state.x, y: state.y })).current;
+  const press = useRef(new Animated.Value(0)).current;
+  const opacity = useRef(new Animated.Value(0)).current;
+  const chromeEpoch = ui.chromeEpoch ?? 0;
+  const { ref: layerRef, origin, measure } = useOverlayOrigin();
+
+  useEffect(() => CursorController.subscribe(setState), []);
+
+  useEffect(() => {
+    if (!running && state.visible) {
+      CursorController.hide();
+    }
+  }, [running, state.visible]);
+
+  useEffect(() => {
+    if (running && state.visible) {
+      TaskStore.liftChrome();
+    }
+  }, [running, state.visible, state.x, state.y]);
+
+  useEffect(() => {
+    const duration = Math.max(0, state.moveDurationMs ?? 0);
+    const to = {
+      x: state.x - origin.x - CURSOR_TIP_X,
+      y: state.y - origin.y - CURSOR_TIP_Y,
+    };
+    if (duration <= 0) {
+      anim.stopAnimation();
+      anim.setValue(to);
+      return;
+    }
+    Animated.timing(anim, {
+      toValue: to,
+      duration,
+      // Reduce native animation work while Fabric registers views during navigation.
+      useNativeDriver: false,
+    }).start();
+  }, [state.x, state.y, state.moveDurationMs, origin.x, origin.y, anim]);
+
+  useEffect(() => {
+    Animated.spring(press, {
+      toValue: state.pressing ? 1 : 0,
+      useNativeDriver: false,
+      friction: 6,
+    }).start();
+  }, [state.pressing, press]);
+
+  const show = running && state.visible;
+
+  useEffect(() => {
+    if (show) {
+      opacity.stopAnimation();
+      opacity.setValue(1);
+      return;
+    }
+    Animated.timing(opacity, {
+      toValue: 0,
+      duration: 80,
+      useNativeDriver: false,
+    }).start();
+  }, [show, opacity]);
+
+  if (!show) return null;
+
+  const scale = press.interpolate({
+    inputRange: [0, 1],
+    outputRange: [1, 0.88],
+  });
+
+  return (
+    <KokoHostOverlay liftToken={chromeEpoch}>
+      <View
+        ref={layerRef}
+        onLayout={measure}
+        testID={KOKO_CURSOR_TEST_ID}
+        nativeID={KOKO_CURSOR_TEST_ID}
+        collapsable={false}
+        pointerEvents="none"
+        style={styles.layer}
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      >
+        <Animated.View
+          style={[
+            styles.cursor,
+            {
+              opacity,
+              transform: [...anim.getTranslateTransform(), { scale }],
+            },
+          ]}
+        >
+          <PointerHand />
+        </Animated.View>
+      </View>
+    </KokoHostOverlay>
+  );
+}
+
+const styles = StyleSheet.create({
+  layer: {
+    ...StyleSheet.absoluteFillObject,
+    backgroundColor: 'transparent',
+  },
+  cursor: {
+    position: 'absolute',
+    width: CURSOR_W,
+    height: CURSOR_H,
+    left: 0,
+    top: 0,
+  },
+});

package/src/cursor/PointerHand.tsx

@@ -0,0 +1,49 @@
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+import { CURSOR_H, CURSOR_W, HAND_SHAPES, HAND_UNIT, HAND_STROKE } from './pointer';
+
+/**
+ * The agent's pointer: a hand with the index finger extended.
+ *
+ * Drawn from views rather than an image. The SDK's assets sit outside the
+ * host's Metro project root, and a host that rewrites asset paths (monorepos
+ * commonly do) can leave the request unresolvable — the pointer then silently
+ * does not render, which is the one thing the user watches to know the agent
+ * is acting. Views cannot fail that way, and they stay sharp at any density.
+ *
+ * Two passes: dark shapes inflated to form the outline, then the white fill
+ * over them. Overlaps within a pass are invisible, so the union reads as one
+ * silhouette with no internal seams.
+ */
+export function PointerHand() {
+  return (
+    <View style={styles.hand} pointerEvents="none">
+      {renderLayer(HAND_STROKE, '#131313')}
+      {renderLayer(0, '#FFFFFF')}
+    </View>
+  );
+}
+
+function renderLayer(inflate: number, color: string) {
+  return HAND_SHAPES.map(([x, y, w, h, r], i) => (
+    <View
+      key={`${color}-${i}`}
+      style={{
+        position: 'absolute',
+        left: (x - inflate) * HAND_UNIT,
+        top: (y - inflate) * HAND_UNIT,
+        width: (w + inflate * 2) * HAND_UNIT,
+        height: (h + inflate * 2) * HAND_UNIT,
+        borderRadius: (r + inflate) * HAND_UNIT,
+        backgroundColor: color,
+      }}
+    />
+  ));
+}
+
+const styles = StyleSheet.create({
+  hand: {
+    width: CURSOR_W,
+    height: CURSOR_H,
+  },
+});

package/src/cursor/controller.ts

@@ -0,0 +1,98 @@
+type CursorListener = (state: CursorState) => void;
+
+export type CursorState = {
+  visible: boolean;
+  x: number;
+  y: number;
+  pressing: boolean;
+  /** How long the overlay should animate to (x, y). 0 = snap. */
+  moveDurationMs: number;
+};
+
+const DEFAULT: CursorState = {
+  visible: false,
+  x: 0,
+  y: 0,
+  pressing: false,
+  moveDurationMs: 0,
+};
+
+/**
+ * Imperative cursor controller used by KokoAgent; CursorOverlay subscribes.
+ */
+class CursorControllerImpl {
+  private state: CursorState = { ...DEFAULT };
+  private listeners = new Set<CursorListener>();
+
+  subscribe(listener: CursorListener): () => void {
+    this.listeners.add(listener);
+    listener(this.state);
+    return () => this.listeners.delete(listener);
+  }
+
+  getState(): CursorState {
+    return this.state;
+  }
+
+  private emit() {
+    for (const l of this.listeners) l(this.state);
+  }
+
+  showAt(x: number, y: number, moveDurationMs = 0) {
+    this.state = {
+      ...this.state,
+      visible: true,
+      x,
+      y,
+      moveDurationMs,
+    };
+    this.emit();
+  }
+
+  hide() {
+    this.state = { ...DEFAULT };
+    this.emit();
+  }
+
+  setPressing(pressing: boolean) {
+    this.state = { ...this.state, pressing };
+    this.emit();
+  }
+
+  /**
+   * Start moving toward the target immediately, then resolve when the
+   * visual move should have finished — so tap happens after the cursor arrives.
+   */
+  async moveTo(x: number, y: number, durationMs: number): Promise<void> {
+    const ms = Math.max(0, Math.floor(durationMs));
+
+    // First appearance: snap near target so we don't fly in from (0,0).
+    // Wait long enough for CursorOverlay's transparent Modal to present
+    // (hosts with native-stack often need >100ms; 32ms left it invisible).
+    if (!this.state.visible) {
+      this.showAt(x, y, 0);
+      await sleep(140);
+      return;
+    }
+
+    const dx = x - this.state.x;
+    const dy = y - this.state.y;
+    const dist = Math.hypot(dx, dy);
+    // Tiny hops: snap; longer moves: animate, then wait for arrival.
+    if (dist < 8 || ms === 0) {
+      this.showAt(x, y, 0);
+      await sleep(24);
+      return;
+    }
+
+    this.showAt(x, y, ms);
+    // Allow React to start Animated.timing, then wait for arrival.
+    await sleep(ms + 24);
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export const CursorController = new CursorControllerImpl();

package/src/cursor/pointer.ts

@@ -0,0 +1,40 @@
+/**
+ * Geometry for the agent's on-screen pointer.
+ *
+ * Two overlays draw it (KokoObserver when the progress chrome is mounted,
+ * CursorOverlay otherwise), so this lives in one place: a hotspot that
+ * disagreed between them would put the pointer somewhere the tap did not go.
+ */
+
+/** Design grid the hand is laid out on. */
+const GRID_W = 34;
+const GRID_H = 44;
+
+/** Keep the grid ratio so the drawing is not squashed. */
+export const CURSOR_W = 26;
+export const CURSOR_H = Math.round((CURSOR_W * GRID_H) / GRID_W);
+
+/** Points per grid unit. */
+export const HAND_UNIT = CURSOR_W / GRID_W;
+
+/** Outline weight, in grid units. */
+export const HAND_STROKE = 1.6;
+
+/**
+ * The hand as a union of rounded bars: `[x, y, width, height, radius]` in grid
+ * units. Order is back to front, though within a layer it does not matter.
+ */
+export const HAND_SHAPES: ReadonlyArray<
+  readonly [number, number, number, number, number]
+> = [
+  [10, 1.5, 7, 24.5, 3.5], // index finger, extended — its tip is the hotspot
+  [16.5, 17, 6.5, 13, 3.2], // middle, folded
+  [21.5, 19, 6.5, 12, 3.2], // ring, folded
+  [26, 21.5, 5.5, 10.5, 2.7], // little, folded
+  [7, 24, 24, 18, 6.5], // palm
+  [2.5, 27, 9.5, 7, 3.5], // thumb, across the side of the palm
+];
+
+/** The index fingertip — this is what lands on the tap coordinate. */
+export const CURSOR_TIP_X = 13.5 * HAND_UNIT;
+export const CURSOR_TIP_Y = 0.6 * HAND_UNIT;