@intentcomputing/koko-agent-sdk 1.0.1

package/src/client/loopDetect.ts

@@ -0,0 +1,213 @@
+/**
+ * Idle / dead-loop detection (mirrors SDK client + KokoAgent explore/escape).
+ * Stop on no-progress loops only — not because a goal needs many steps.
+ */
+
+export type HistoryLike = {
+  tool: string;
+  args?: Record<string, unknown>;
+  result: string;
+  ok?: boolean;
+};
+
+export function actionFingerprint(item: HistoryLike): string {
+  const tool = item.tool;
+  const args = item.args ?? {};
+  if (tool === "tap") {
+    const sel = args.selector as { match?: unknown } | undefined;
+    const matchKey = sel?.match != null ? JSON.stringify(sel.match).slice(0, 100) : "";
+    const nodeId = String(args.nodeId || "").trim();
+    const label = String(args.label || "").trim();
+    return `tap:${(matchKey || nodeId || label || "target").slice(0, 100)}`;
+  }
+  if (tool === "type") {
+    return `type:${String(args.text ?? "").slice(0, 40)}`;
+  }
+  if (tool === "find") {
+    return `find:${JSON.stringify(args.match ?? {}).slice(0, 100)}`;
+  }
+  if (tool === "swipe") {
+    const from = args.from as { x?: number; y?: number } | undefined;
+    const to = args.to as { x?: number; y?: number } | undefined;
+    return `swipe:${Math.round((from?.x ?? 0) / 40)},${Math.round((from?.y ?? 0) / 40)}→${Math.round(
+      (to?.x ?? 0) / 40,
+    )},${Math.round((to?.y ?? 0) / 40)}`;
+  }
+  if (tool === "pinch") {
+    const c = args.center as { x?: number; y?: number } | undefined;
+    const scale = Number(args.scale ?? 1);
+    return `pinch:${Math.round((c?.x ?? 0) / 40)},${Math.round((c?.y ?? 0) / 40)}×${scale.toFixed(2)}`;
+  }
+  if (tool === "dump") {
+    if (/empty|未识别|screen:\s*\(empty\)/i.test(item.result)) return "dump:empty";
+    return `dump:${item.result.replace(/\s+/g, " ").slice(0, 48)}`;
+  }
+  if (tool === "ask_user") return `ask:${String(args.question ?? "").slice(0, 40)}`;
+  return `${tool}:${JSON.stringify(args).slice(0, 60)}`;
+}
+
+function screenOf(item: HistoryLike): string {
+  const m = item.result.match(/(?:^|\|\|\s*)screen:\s*([^\r\n]*)/i);
+  return m?.[1]?.trim() ?? "";
+}
+
+/** Older hosts may return body text without a screen marker; retain all of it. */
+function observationOf(item: HistoryLike): string {
+  return (screenOf(item) || item.result).replace(/\s+/g, " ").trim();
+}
+
+function sameObservation(items: HistoryLike[]): boolean {
+  return items.length >= 2 && items.every((h) => observationOf(h) === observationOf(items[0]!));
+}
+
+function isFail(item: HistoryLike): boolean {
+  if (typeof item.ok === "boolean") return !item.ok;
+  return /^(?:fail(?:ed)?|error|null|tap_failed|tap_noop|scroll_noop|no_focus|empty|未识别)(?:\b|[:：\s(]|$)/i.test(item.result.trim());
+}
+
+/** Actions whose whole point is to change something on screen. */
+const MUTATING = new Set(["tap", "swipe", "pinch", "type"]);
+
+/** The client ran it and the screen did not react. */
+function hadNoEffect(item: HistoryLike): boolean {
+  return item.ok === false || /^(?:tap_noop|tap_failed|scroll_noop|no_focus)\b/i.test(item.result.trim());
+}
+
+/**
+ * Selector wording drifts between retries — grounded text, then the a11y
+ * label, then a nodeId, then a coordinate fallback — so fingerprint equality
+ * misses the most common stall: aiming at the same place through a different
+ * description each time.
+ *
+ * Comparing whole screens across steps does not catch it either, because a
+ * rotating ad or carousel changes the fingerprint while the page stays put.
+ * Trust the per-step verdict instead: the client captures before and after
+ * around each action, moments apart, and marks it `tap_noop` when nothing
+ * moved. A window whose only attempts to change something all reported no
+ * effect is stuck, however the calls were phrased and whatever else animates.
+ */
+function madeNoProgress(history: HistoryLike[]): boolean {
+  const mutating = history.slice(-4).filter((h) => MUTATING.has(h.tool));
+  const preDispatch = mutating.filter(h => /^pre_dispatch:/i.test(h.result));
+  const dispatched = mutating.filter(h => !/^pre_dispatch:/i.test(h.result));
+  if (preDispatch.length >= 3 && preDispatch.length === mutating.length) return true;
+  const dead = dispatched.filter(hadNoEffect);
+  return dead.length >= 2 && dead.length === dispatched.length;
+}
+
+/** Bound interleaved find/dump loops on one unchanged observed screen. */
+function repeatedReadOnly(history: HistoryLike[]): boolean {
+  const tail = history.slice(-8);
+  if (tail.length < 8 || !tail.every(h => h.tool === 'find' || h.tool === 'dump')) return false;
+  const finds = tail.filter(h => h.tool === 'find');
+  const screens = tail.map(screenOf).filter(Boolean);
+  if (finds.length < 3 || screens.length < 3 || !screens.every(s => s === screens[0])) return false;
+  const fps = finds.map(actionFingerprint);
+  return fps.some(fp => fps.filter(value => value === fp).length >= 3) || finds.every(isFail);
+}
+
+export function isLooping(history: HistoryLike[]): boolean {
+  const recent = history.slice(-5);
+  if (recent.length < 3) return false;
+
+  if (madeNoProgress(history)) return true;
+  if (repeatedReadOnly(history)) return true;
+
+  const fps = recent.map(actionFingerprint);
+  const last = fps[fps.length - 1]!;
+  const sameFpCount = fps.filter((f) => f === last).length;
+  const screenStagnant = recent.length >= 3 && sameObservation(recent);
+  const lastThree = recent.slice(-3);
+  const allFail = lastThree.every(isFail);
+  const identicalResults =
+    lastThree.length === 3 &&
+    lastThree.every(
+      (h) => h.result === lastThree[0]!.result,
+    );
+
+  // dump/find are observe — identical verify dumps must not abort mid-goal.
+  if (sameFpCount >= 3) {
+    const lastTool = recent[recent.length - 1]?.tool;
+    if (lastTool !== "dump" && lastTool !== "find") {
+      if (allFail || identicalResults || screenStagnant) return true;
+    }
+  }
+
+  if (recent.length >= 4) {
+    const a = fps[fps.length - 1];
+    const b = fps[fps.length - 2];
+    if (a && b && a !== b && fps[fps.length - 3] === a && fps[fps.length - 4] === b) {
+      // Alternating actions are common in valid workflows (select/continue,
+      // increment/confirm, tap/verify). Only stop when each phase also returns
+      // to the same observation, rather than when actions alone form A-B-A-B.
+      const cycle = recent.slice(-4);
+      if (observationOf(cycle[0]!) === observationOf(cycle[2]!) &&
+          observationOf(cycle[1]!) === observationOf(cycle[3]!)) return true;
+    }
+  }
+
+  // Observe-only thrash: a couple dumps for verify is ok; 3+ identical scans = stuck.
+  const trailing = recent.slice(-3);
+  if (
+    trailing.length >= 3 &&
+    trailing.every((h) => h.tool === "dump") &&
+    sameObservation(trailing)
+  ) {
+    return true;
+  }
+
+  const fails = recent.filter(isFail);
+  if (fails.length >= 3) {
+    const failFps = fails.map(actionFingerprint);
+    const failScreens = fails.map(screenOf).filter(Boolean);
+    const sameScreen = failScreens.length !== fails.length || failScreens.every(s => s === failScreens[0]);
+    if (failFps.length >= 3 && sameScreen && failFps.every((f) => f === failFps[0])) return true;
+  }
+
+  // Same screen + same *mutating* tool = stuck. Pure dump/find is verification.
+  if (screenStagnant) {
+    const tools = recent.slice(-3).map((h) => h.tool);
+    const t0 = tools[0];
+    if (
+      tools.every((t) => t === t0) &&
+      t0 !== "type" &&
+      t0 !== "dump" &&
+      t0 !== "find"
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function isNearLoop(history: HistoryLike[]): boolean {
+  const recent = history.slice(-3);
+  if (recent.length < 2) return false;
+
+  // A bounded loading/verification wait can repeat; warn only if unchanged.
+  const trailingDumps = recent.slice(-2);
+  if (trailingDumps.length >= 2 && trailingDumps.every((h) => h.tool === "dump") &&
+      sameObservation(trailingDumps)) {
+    return true;
+  }
+
+  const fps = recent.map(actionFingerprint);
+  const last = fps[fps.length - 1]!;
+  if (fps.filter((f) => f === last).length < 2) return false;
+  if (sameObservation(recent)) return true;
+  return (
+    recent.slice(-2).every(isFail) ||
+    recent.slice(-2).every((h) => h.result === recent[recent.length - 1]!.result)
+  );
+}
+
+export const LOOP_ESCAPE_HINT = `【恢复评估 — 近期观察或动作重复，先核验当前状态】
+- 对照用户目标和最新证据：已验证全部结果才 done(true)；重复或空转本身不代表成功
+- 加载、转场或已提交操作仍待结果时，可以在客户端预算内用 dump 只读核验；持续不变则如实 done(false)说明未确认，不重提请求或重走已完成流程
+- tap_noop / tap_failed 后先核对当前控件与状态；只有存在有证据且安全的替代动作才调整 selector、目标或路径，不能为了逃逸而猜点
+- 与当前子目标相关的标题、正文、页码或状态持续变化时，同名或交替按钮仍可能是正常进展；不要按固定点击次数或动作序列认定循环
+- 下一步控件确实可见、可操作且属于当前目标时再 tap/type；已满足的选中状态不重复切换
+- 仅目标属于当前列表且有滚动区域边界时才 swipe 查找；手势起终点在区域内，不能用滑动猜测导航
+- 数值控件按实际类型、当前值、范围和用户精度要求调整，不预设手势方向；无效果、到边界或缺少证据时说明受阻
+- find/tap 使用最新能力里的文案或 id；缺少安全下一步时允许只读观察或如实结束，不强制切换路径`;

package/src/client/recentSearch.ts

@@ -0,0 +1,47 @@
+import type { ViewNode } from '../types';
+import type { GatewayAction } from './GatewayClient';
+import { find } from '../selector/match';
+
+const norm = (s: string) => s.trim().toLocaleLowerCase();
+const isInput = (n: ViewNode) => /textfield|textinput|edittext|uitextview|textarea/i.test(n.type) && !/label$/i.test(n.type);
+const label = (n: ViewNode) => n.text || n.accessibilityLabel || '';
+const recent = /^(recent(?: searches| search| history)?|search history|最近(?:搜索|记录)?|搜索历史|历史搜索|历史记录)$/i;
+
+/** Only replace a search query with a uniquely identified visible recent item. */
+export function recentSearchAction(action: GatewayAction, root: ViewNode | null, goal: string): GatewayAction | null {
+  if (action.tool !== 'type' || !root || !action.args.text.trim()) return null;
+  const query = norm(action.args.text);
+  if (!norm(goal).includes(query) || !/\b(open|find|search|look up)\b|打开|搜索|查找/i.test(goal) ||
+      /\b(type|enter|input|write|paste)\b|输入|键入|填写|粘贴/i.test(goal)) return null;
+  const nodes: ViewNode[] = [];
+  const walk = (n: ViewNode) => {
+    if (n.visible === false || n.enabled === false) return;
+    nodes.push(n);
+    n.children.forEach(walk);
+  };
+  walk(root);
+  const inputNodes = nodes.filter(isInput);
+  const fields = inputNodes.filter(n => !inputNodes.some(other => other.id.startsWith(n.id + '/')));
+  if (fields.length !== 1 || fields[0]?.secure || !/search|搜索|查找/i.test(label(fields[0]!))) return null;
+  if (action.args.nodeId && action.args.nodeId !== fields[0]!.id && !fields[0]!.id.startsWith(action.args.nodeId + '/')) return null;
+  if (action.args.selector) {
+    const selected = find(root, action.args.selector);
+    if (!selected || (selected.id !== fields[0]!.id &&
+      !fields[0]!.id.startsWith(selected.id + '/') && !selected.id.startsWith(fields[0]!.id + '/'))) return null;
+  }
+
+  const headings = nodes.filter(n => recent.test(label(n).trim()));
+  const candidates = nodes.filter(n => n.clickable && norm(label(n)) === query && !isInput(n));
+  if (!headings.length || !candidates.length) return null;
+  // Require a local section containing a recent heading and the candidate, not
+  // just two unrelated nodes somewhere on the page. Ancestors that include the
+  // search input or cover most of the screen cannot establish that relation.
+  const related = candidates.filter(candidate => headings.some(heading => nodes.some(section =>
+    section.id !== root.id && section.id !== fields[0]!.id &&
+    heading.id.startsWith(section.id + '/') && candidate.id.startsWith(section.id + '/') &&
+    !fields[0]!.id.startsWith(section.id + '/') &&
+    section.frame.height < root.frame.height * 0.7)));
+  const leaves = related.filter(n => !related.some(other => other.id.startsWith(n.id + '/')));
+  if (leaves.length !== 1) return null;
+  return { tool: 'tap', args: { nodeId: leaves[0]!.id, label: label(leaves[0]!) } };
+}

package/src/client/walletChoiceGuard.ts

@@ -0,0 +1,15 @@
+import type { GatewayAction } from './GatewayClient';
+
+/** Protect a host-wallet request from accidentally selecting an unrelated provider. */
+export function wrongHostWalletChoice(goal: string, action: GatewayAction, choices: string[], aliases: string[], observedLabel?: string): boolean {
+  if (action.tool !== 'tap' || !choices.length || !aliases.length) return false;
+  const normalize = (s: string) => s.toLocaleLowerCase().replace(/[^\p{L}\p{N}]/gu, '');
+  const g = normalize(goal);
+  // An explicitly named provider is a different user request, not a host-wallet default.
+  if (choices.some(choice => g.includes(normalize(choice)))) return false;
+  const matches = action.args.selector?.match || [];
+  const labels = [observedLabel, action.args.label, ...matches.flatMap(rule =>
+    ['text', 'accessibilityLabel'].map(key => (rule as Record<string, unknown>)[key]).filter((x): x is string => typeof x === 'string'))]
+    .filter((s): s is string => typeof s === 'string').map(normalize);
+  return choices.some(choice => labels.includes(normalize(choice)) && !aliases.some(alias => normalize(alias) === normalize(choice)));
+}

package/src/client/webResultCategory.ts

@@ -0,0 +1,28 @@
+import type { ViewNode } from '../types';
+import type { GatewayAction, AgentHistoryItem } from './GatewayClient';
+
+/** Select a visible app-results category only when the user's query is on this page. */
+export function webResultCategory(action: GatewayAction, root: ViewNode | null, goal: string, history: AgentHistoryItem[]): GatewayAction | null {
+  if (action.tool !== 'dump' || !root || !/(connect|连接|連接)/i.test(goal) || !/(wallet|钱包|錢包)/i.test(goal)) return null;
+  const nodes: ViewNode[] = [];
+  const visit = (node: ViewNode) => {
+    if (node.visible === false || node.enabled === false) return;
+    nodes.push(node);
+    node.children.forEach(visit);
+  };
+  visit(root);
+  const norm = (s: string) => s.trim().toLocaleLowerCase();
+  const fields = nodes.filter(n => /textfield|textinput|edittext/i.test(n.type) && !/label$/i.test(n.type));
+  if (!fields.some(n => {
+    const value = norm(n.text || n.accessibilityLabel || '');
+    return value.length >= 3 && norm(goal).includes(value);
+  })) return null;
+  const names = new Set(nodes.map(n => norm(n.text || n.accessibilityLabel || '')));
+  if (![...names].some(name => /^(tokens|代币|代幣)$/.test(name))) return null;
+  const candidates = nodes.filter(n => n.clickable && /^(dapps|dapp|应用|應用)$/.test(norm(n.text || n.accessibilityLabel || '')) && !n.selected);
+  const leaves = candidates.filter(n => !candidates.some(other => other.id.startsWith(n.id + '/')));
+  if (leaves.length !== 1) return null;
+  const node = leaves[0]!;
+  if (history.some(h => h.tool === 'tap' && h.args?.nodeId === node.id)) return null;
+  return { tool: 'tap', args: { nodeId: node.id, label: node.text || node.accessibilityLabel } };
+}

package/src/commercial/AccountStore.ts

@@ -0,0 +1,85 @@
+import { GatewayClient, type GatewayConfig } from '../client/GatewayClient';
+import type { KokoAccountSnapshot, KokoEntitlements, KokoPlanId } from '../types';
+import { DEFAULT_ENTITLEMENTS, emptyAccount } from './branding';
+import { isTrustedEntitlementHost } from './trust';
+import { resolveGatewayBaseUrl } from '../client/GatewayClient';
+
+type Listener = (account: KokoAccountSnapshot | null) => void;
+
+function stripUntrustedBranding(
+  account: KokoAccountSnapshot,
+  baseUrl: string,
+): KokoAccountSnapshot {
+  if (isTrustedEntitlementHost(baseUrl)) return account;
+  return {
+    ...account,
+    entitlements: {
+      ...account.entitlements,
+      custom_branding: false,
+    },
+  };
+}
+
+class AccountStoreImpl {
+  private account: KokoAccountSnapshot | null = null;
+  private listeners = new Set<Listener>();
+  private inflight: Promise<KokoAccountSnapshot | null> | null = null;
+
+  get(): KokoAccountSnapshot | null {
+    return this.account;
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    listener(this.account);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private emit() {
+    for (const l of this.listeners) l(this.account);
+  }
+
+  async refresh(gateway: GatewayConfig): Promise<KokoAccountSnapshot | null> {
+    if (this.inflight) return this.inflight;
+    let baseUrl: string;
+    try {
+      baseUrl = resolveGatewayBaseUrl(gateway);
+    } catch {
+      if (!this.account) {
+        this.account = emptyAccount();
+        this.emit();
+      }
+      return this.account;
+    }
+    this.inflight = (async () => {
+      try {
+        const client = new GatewayClient(gateway);
+        const me = await client.me();
+        this.account = stripUntrustedBranding(me, baseUrl);
+        this.emit();
+        return this.account;
+      } catch {
+        if (!this.account) {
+          this.account = emptyAccount();
+          this.emit();
+        }
+        return this.account;
+      } finally {
+        this.inflight = null;
+      }
+    })();
+    return this.inflight;
+  }
+
+  entitlements(): KokoEntitlements {
+    return this.account?.entitlements ?? { ...DEFAULT_ENTITLEMENTS };
+  }
+
+  plan(): KokoPlanId {
+    return this.account?.plan ?? 'free';
+  }
+}
+
+export const AccountStore = new AccountStoreImpl();

package/src/commercial/AgentDebug.ts

@@ -0,0 +1,142 @@
+import { resolveDebugLogging } from './devMode';
+import type { KokoAgentConfig } from '../types';
+import type { Affordance } from '../privacy/screenModel';
+import { extractAffordances } from '../privacy/screenModel';
+import { HostActionsStore } from '../host/HostActions';
+import type { ViewNode } from '../types';
+
+type Cfg = Pick<KokoAgentConfig, 'debug' | 'devMode'> | undefined;
+
+/**
+ * Developer-facing logs: what the SDK observed in the host App
+ * (controls / fields / actions). Never logs security policy internals.
+ */
+export const AgentDebug = {
+  enabled(config?: Cfg): boolean {
+    return resolveDebugLogging(config);
+  },
+
+  /** High-level run lifecycle (goal only, no policy). */
+  runStart(config: Cfg, goal: string) {
+    if (!resolveDebugLogging(config)) return;
+    // eslint-disable-next-line no-console
+    console.log('[koko] 开始任务:', goal.slice(0, 120));
+  },
+
+  runEnd(config: Cfg, summary: string, ok: boolean) {
+    if (!resolveDebugLogging(config)) return;
+    // eslint-disable-next-line no-console
+    console.log(ok ? '[koko] 任务完成:' : '[koko] 任务结束:', summary.slice(0, 160));
+  },
+
+  /** The dump stopped at its depth cap, so the page body never reached us. */
+  dumpTruncated(config: Cfg, cap: number) {
+    if (!resolveDebugLogging(config)) return;
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[koko] 视图树在 maxDepth=${cap} 处被截断，页面正文可能完全缺失（只剩外层导航）。` +
+        '请调大 dumpMaxDepth。',
+    );
+  },
+
+  /** Capabilities discovered on the current screen. */
+  screenCapabilities(config: Cfg, tree: ViewNode | null | undefined) {
+    if (!resolveDebugLogging(config)) return;
+    const items = tree ? extractAffordances(tree, 24) : [];
+    const host = HostActionsStore.getActions();
+    if (!items.length && !host.length) {
+      // eslint-disable-next-line no-console
+      console.log('[koko] 当前界面: 未识别到可操作控件');
+      return;
+    }
+    const lines = [
+      ...items.map(formatAffordance),
+      ...host.map(
+        (a) => `宿主声明「${a.label}」${a.testID ? `(testID=${a.testID})` : ''}`,
+      ),
+    ];
+    // eslint-disable-next-line no-console
+    console.log(`[koko] 当前界面可用能力 (${lines.length}):\n  - ${lines.join('\n  - ')}`);
+  },
+
+  /** What the agent is about to do in the App (user-visible action). */
+  appAction(
+    config: Cfg,
+    step: number,
+    tool: string,
+    detail?: string,
+  ) {
+    if (!resolveDebugLogging(config)) return;
+    const label = actionLabel(tool, detail);
+    // eslint-disable-next-line no-console
+    console.log(`[koko] 步骤 ${step}: ${label}`);
+  },
+
+  /** Soft failure for developers — generic, no rule leakage. */
+  runIssue(config: Cfg, message: string) {
+    if (!resolveDebugLogging(config)) return;
+    const safe = sanitizeDevMessage(message);
+    // eslint-disable-next-line no-console
+    console.warn('[koko] 任务遇到问题:', safe);
+  },
+};
+
+function formatAffordance(a: Affordance): string {
+  const kind =
+    a.kind === 'button'
+      ? '按钮'
+      : a.kind === 'field'
+        ? '输入框'
+        : a.kind === 'row'
+          ? '列表项'
+          : a.kind === 'link'
+            ? '链接'
+            : a.kind === 'sheet'
+              ? '弹层按钮'
+              : a.kind === 'toggle'
+                ? '开关'
+                : a.kind === 'adjustable'
+                  ? '调节控件'
+                  : '控件';
+  const near = a.near ? `（附近: ${a.near.slice(0, 40)}）` : '';
+  return `${kind}「${a.label || '(无文案)'}」${near}`;
+}
+
+function actionLabel(tool: string, detail?: string): string {
+  const d = detail?.trim();
+  switch (tool) {
+    case 'dump':
+      return '扫描当前界面';
+    case 'find':
+      return d ? `定位「${d}」` : '定位控件';
+    case 'tap':
+      return d ? `点击「${d}」` : '点击';
+    case 'swipe':
+      return d ? `滑动（${d}）` : '滑动';
+    case 'pinch':
+      return d ? `双指缩放（${d}）` : '双指缩放';
+    case 'type':
+      return d ? `输入「${d}」` : '输入文字';
+    case 'ask_user':
+      return '等待你在 App 内操作';
+    case 'done':
+      return d ? `结束：${d}` : '结束';
+    default:
+      return d ? `${tool}: ${d}` : tool;
+  }
+}
+
+/** Strip security/policy jargon from messages shown in debug console. */
+export function sanitizeDevMessage(message: string): string {
+  const lower = message.toLowerCase();
+  if (
+    /execution_permit|execution permit|permit expired|gateway host|allowlist|devmode|custom_branding|entitlement/i.test(
+      message,
+    )
+  ) {
+    if (/quota|429/.test(lower)) return '今日用量已用尽，请稍后再试或联系服务商扩容';
+    if (/unauthorized|401/.test(lower)) return '鉴权失败，请检查 gateway.token';
+    return '暂时无法继续操作，请稍后重试或检查网络与账号配置';
+  }
+  return message.slice(0, 200);
+}

package/src/commercial/ExecutionGuard.ts

@@ -0,0 +1,67 @@
+/**
+ * Soft client gate: local dump/tap/swipe/type require a short-lived
+ * execution_permit from the official (or local-lab) gateway session.
+ * Always enforced — debug logging does not bypass this.
+ */
+
+export type GuardedAction = 'dump' | 'find' | 'tap' | 'swipe' | 'pinch' | 'type' | 'screenshot';
+
+function peekExp(permit: string): number | null {
+  try {
+    const [payloadB64] = permit.split('.');
+    if (!payloadB64) return null;
+    const pad =
+      payloadB64.length % 4 === 0
+        ? ''
+        : '='.repeat(4 - (payloadB64.length % 4));
+    const json = globalThis.atob
+      ? globalThis.atob(payloadB64.replace(/-/g, '+').replace(/_/g, '/') + pad)
+      : Buffer.from(
+          payloadB64.replace(/-/g, '+').replace(/_/g, '/') + pad,
+          'base64',
+        ).toString('utf8');
+    const payload = JSON.parse(json) as { exp?: number };
+    return typeof payload.exp === 'number' ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+
+class ExecutionGuardImpl {
+  private permit: string | null = null;
+  private sessionId: string | null = null;
+
+  setPermit(permit: string | null, sessionId?: string | null) {
+    this.permit = permit;
+    if (sessionId !== undefined) this.sessionId = sessionId;
+  }
+
+  getPermit() {
+    return this.permit;
+  }
+
+  getSessionId() {
+    return this.sessionId;
+  }
+
+  clear() {
+    this.permit = null;
+    this.sessionId = null;
+  }
+
+  assert(action: GuardedAction) {
+    if (!this.permit) {
+      throw new Error(
+        `KokoAgent: ${action} is only available while a goal is running. Use runGoal().`,
+      );
+    }
+    const exp = peekExp(this.permit);
+    if (exp != null && exp < Math.floor(Date.now() / 1000)) {
+      throw new Error(
+        `KokoAgent: session timed out during ${action}. Please run the goal again.`,
+      );
+    }
+  }
+}
+
+export const ExecutionGuard = new ExecutionGuardImpl();

package/src/commercial/UsageBus.ts

@@ -0,0 +1,44 @@
+import type { KokoUsageEvent } from '../types';
+
+type Listener = (event: KokoUsageEvent) => void;
+
+/**
+ * Fan-out for usage / lifecycle events. Host `onUsageEvent` is wired here.
+ * Never used to gate execution.
+ */
+class UsageBusImpl {
+  private listeners = new Set<Listener>();
+  private recent: KokoUsageEvent[] = [];
+  private readonly maxRecent = 100;
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  emit(event: KokoUsageEvent) {
+    this.recent.push(event);
+    if (this.recent.length > this.maxRecent) {
+      this.recent.splice(0, this.recent.length - this.maxRecent);
+    }
+    for (const l of this.listeners) {
+      try {
+        l(event);
+      } catch {
+        // host callbacks must not break the agent
+      }
+    }
+  }
+
+  getRecent(): KokoUsageEvent[] {
+    return [...this.recent];
+  }
+
+  clear() {
+    this.recent = [];
+  }
+}
+
+export const UsageBus = new UsageBusImpl();