@intentcomputing/koko-agent-sdk 1.0.1

package/lib/module/client/loopDetect.js

@@ -0,0 +1,177 @@
+"use strict";
+
+/**
+ * Idle / dead-loop detection (mirrors SDK client + KokoAgent explore/escape).
+ * Stop on no-progress loops only — not because a goal needs many steps.
+ */
+
+export function actionFingerprint(item) {
+  const tool = item.tool;
+  const args = item.args ?? {};
+  if (tool === "tap") {
+    const sel = args.selector;
+    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;
+    const to = args.to;
+    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;
+    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) {
+  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) {
+  return (screenOf(item) || item.result).replace(/\s+/g, " ").trim();
+}
+function sameObservation(items) {
+  return items.length >= 2 && items.every(h => observationOf(h) === observationOf(items[0]));
+}
+function isFail(item) {
+  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) {
+  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) {
+  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) {
+  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) {
+  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) {
+  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；缺少安全下一步时允许只读观察或如实结束，不强制切换路径`;
+//# sourceMappingURL=loopDetect.js.map

package/lib/module/client/loopDetect.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["actionFingerprint","item","tool","args","sel","selector","matchKey","match","JSON","stringify","slice","nodeId","String","trim","label","text","from","to","Math","round","x","y","c","center","scale","Number","toFixed","test","result","replace","question","screenOf","m","observationOf","sameObservation","items","length","every","h","isFail","ok","MUTATING","Set","hadNoEffect","madeNoProgress","history","mutating","filter","has","preDispatch","dispatched","dead","repeatedReadOnly","tail","finds","screens","map","Boolean","s","fps","some","fp","value","isLooping","recent","last","sameFpCount","f","screenStagnant","lastThree","allFail","identicalResults","lastTool","a","b","cycle","trailing","fails","failFps","failScreens","sameScreen","tools","t0","t","isNearLoop","trailingDumps","LOOP_ESCAPE_HINT"],"sourceRoot":"../../../src","sources":["client/loopDetect.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/client/recentSearch.js

@@ -0,0 +1,46 @@
+"use strict";
+
+import { find } from "../selector/match.js";
+const norm = s => s.trim().toLocaleLowerCase();
+const isInput = n => /textfield|textinput|edittext|uitextview|textarea/i.test(n.type) && !/label$/i.test(n.type);
+const label = n => 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, root, goal) {
+  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 = [];
+  const walk = n => {
+    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])
+    }
+  };
+}
+//# sourceMappingURL=recentSearch.js.map

package/lib/module/client/recentSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["find","norm","s","trim","toLocaleLowerCase","isInput","n","test","type","label","text","accessibilityLabel","recent","recentSearchAction","action","root","goal","tool","args","query","includes","nodes","walk","visible","enabled","push","children","forEach","inputNodes","filter","fields","some","other","id","startsWith","length","secure","nodeId","selector","selected","headings","candidates","clickable","related","candidate","heading","section","frame","height","leaves"],"sourceRoot":"../../../src","sources":["client/recentSearch.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/client/walletChoiceGuard.js

@@ -0,0 +1,14 @@
+"use strict";
+
+/** Protect a host-wallet request from accidentally selecting an unrelated provider. */
+export function wrongHostWalletChoice(goal, action, choices, aliases, observedLabel) {
+  if (action.tool !== 'tap' || !choices.length || !aliases.length) return false;
+  const normalize = s => 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[key]).filter(x => typeof x === 'string'))].filter(s => typeof s === 'string').map(normalize);
+  return choices.some(choice => labels.includes(normalize(choice)) && !aliases.some(alias => normalize(alias) === normalize(choice)));
+}
+//# sourceMappingURL=walletChoiceGuard.js.map

package/lib/module/client/walletChoiceGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["wrongHostWalletChoice","goal","action","choices","aliases","observedLabel","tool","length","normalize","s","toLocaleLowerCase","replace","g","some","choice","includes","matches","args","selector","match","labels","label","flatMap","rule","map","key","filter","x","alias"],"sourceRoot":"../../../src","sources":["client/walletChoiceGuard.ts"],"mappings":";;AAEA;AACA,OAAO,SAASA,qBAAqBA,CAACC,IAAY,EAAEC,MAAqB,EAAEC,OAAiB,EAAEC,OAAiB,EAAEC,aAAsB,EAAW;EAChJ,IAAIH,MAAM,CAACI,IAAI,KAAK,KAAK,IAAI,CAACH,OAAO,CAACI,MAAM,IAAI,CAACH,OAAO,CAACG,MAAM,EAAE,OAAO,KAAK;EAC7E,MAAMC,SAAS,GAAIC,CAAS,IAAKA,CAAC,CAACC,iBAAiB,CAAC,CAAC,CAACC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC;EACrF,MAAMC,CAAC,GAAGJ,SAAS,CAACP,IAAI,CAAC;EACzB;EACA,IAAIE,OAAO,CAACU,IAAI,CAACC,MAAM,IAAIF,CAAC,CAACG,QAAQ,CAACP,SAAS,CAACM,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,KAAK;EACvE,MAAME,OAAO,GAAGd,MAAM,CAACe,IAAI,CAACC,QAAQ,EAAEC,KAAK,IAAI,EAAE;EACjD,MAAMC,MAAM,GAAG,CAACf,aAAa,EAAEH,MAAM,CAACe,IAAI,CAACI,KAAK,EAAE,GAAGL,OAAO,CAACM,OAAO,CAACC,IAAI,IACvE,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAACC,GAAG,CAACC,GAAG,IAAKF,IAAI,CAA6BE,GAAG,CAAC,CAAC,CAACC,MAAM,CAAEC,CAAC,IAAkB,OAAOA,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CACpID,MAAM,CAAEjB,CAAC,IAAkB,OAAOA,CAAC,KAAK,QAAQ,CAAC,CAACe,GAAG,CAAChB,SAAS,CAAC;EACnE,OAAOL,OAAO,CAACU,IAAI,CAACC,MAAM,IAAIM,MAAM,CAACL,QAAQ,CAACP,SAAS,CAACM,MAAM,CAAC,CAAC,IAAI,CAACV,OAAO,CAACS,IAAI,CAACe,KAAK,IAAIpB,SAAS,CAACoB,KAAK,CAAC,KAAKpB,SAAS,CAACM,MAAM,CAAC,CAAC,CAAC;AACrI","ignoreList":[]}

package/lib/module/client/webResultCategory.js

@@ -0,0 +1,34 @@
+"use strict";
+
+/** Select a visible app-results category only when the user's query is on this page. */
+export function webResultCategory(action, root, goal, history) {
+  if (action.tool !== 'dump' || !root || !/(connect|连接|連接)/i.test(goal) || !/(wallet|钱包|錢包)/i.test(goal)) return null;
+  const nodes = [];
+  const visit = node => {
+    if (node.visible === false || node.enabled === false) return;
+    nodes.push(node);
+    node.children.forEach(visit);
+  };
+  visit(root);
+  const norm = s => 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
+    }
+  };
+}
+//# sourceMappingURL=webResultCategory.js.map

package/lib/module/client/webResultCategory.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["webResultCategory","action","root","goal","history","tool","test","nodes","visit","node","visible","enabled","push","children","forEach","norm","s","trim","toLocaleLowerCase","fields","filter","n","type","some","value","text","accessibilityLabel","length","includes","names","Set","map","name","candidates","clickable","selected","leaves","other","id","startsWith","h","args","nodeId","label"],"sourceRoot":"../../../src","sources":["client/webResultCategory.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/commercial/AccountStore.js

@@ -0,0 +1,75 @@
+"use strict";
+
+import { GatewayClient } from "../client/GatewayClient.js";
+import { DEFAULT_ENTITLEMENTS, emptyAccount } from "./branding.js";
+import { isTrustedEntitlementHost } from "./trust.js";
+import { resolveGatewayBaseUrl } from "../client/GatewayClient.js";
+function stripUntrustedBranding(account, baseUrl) {
+  if (isTrustedEntitlementHost(baseUrl)) return account;
+  return {
+    ...account,
+    entitlements: {
+      ...account.entitlements,
+      custom_branding: false
+    }
+  };
+}
+class AccountStoreImpl {
+  account = null;
+  listeners = new Set();
+  inflight = null;
+  get() {
+    return this.account;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener(this.account);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit() {
+    for (const l of this.listeners) l(this.account);
+  }
+  async refresh(gateway) {
+    if (this.inflight) return this.inflight;
+    let baseUrl;
+    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() {
+    return this.account?.entitlements ?? {
+      ...DEFAULT_ENTITLEMENTS
+    };
+  }
+  plan() {
+    return this.account?.plan ?? 'free';
+  }
+}
+export const AccountStore = new AccountStoreImpl();
+//# sourceMappingURL=AccountStore.js.map

package/lib/module/commercial/AccountStore.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GatewayClient","DEFAULT_ENTITLEMENTS","emptyAccount","isTrustedEntitlementHost","resolveGatewayBaseUrl","stripUntrustedBranding","account","baseUrl","entitlements","custom_branding","AccountStoreImpl","listeners","Set","inflight","get","subscribe","listener","add","delete","emit","l","refresh","gateway","client","me","plan","AccountStore"],"sourceRoot":"../../../src","sources":["commercial/AccountStore.ts"],"mappings":";;AAAA,SAASA,aAAa,QAA4B,4BAAyB;AAE3E,SAASC,oBAAoB,EAAEC,YAAY,QAAQ,eAAY;AAC/D,SAASC,wBAAwB,QAAQ,YAAS;AAClD,SAASC,qBAAqB,QAAQ,4BAAyB;AAI/D,SAASC,sBAAsBA,CAC7BC,OAA4B,EAC5BC,OAAe,EACM;EACrB,IAAIJ,wBAAwB,CAACI,OAAO,CAAC,EAAE,OAAOD,OAAO;EACrD,OAAO;IACL,GAAGA,OAAO;IACVE,YAAY,EAAE;MACZ,GAAGF,OAAO,CAACE,YAAY;MACvBC,eAAe,EAAE;IACnB;EACF,CAAC;AACH;AAEA,MAAMC,gBAAgB,CAAC;EACbJ,OAAO,GAA+B,IAAI;EAC1CK,SAAS,GAAG,IAAIC,GAAG,CAAW,CAAC;EAC/BC,QAAQ,GAA+C,IAAI;EAEnEC,GAAGA,CAAA,EAA+B;IAChC,OAAO,IAAI,CAACR,OAAO;EACrB;EAEAS,SAASA,CAACC,QAAkB,EAAc;IACxC,IAAI,CAACL,SAAS,CAACM,GAAG,CAACD,QAAQ,CAAC;IAC5BA,QAAQ,CAAC,IAAI,CAACV,OAAO,CAAC;IACtB,OAAO,MAAM;MACX,IAAI,CAACK,SAAS,CAACO,MAAM,CAACF,QAAQ,CAAC;IACjC,CAAC;EACH;EAEQG,IAAIA,CAAA,EAAG;IACb,KAAK,MAAMC,CAAC,IAAI,IAAI,CAACT,SAAS,EAAES,CAAC,CAAC,IAAI,CAACd,OAAO,CAAC;EACjD;EAEA,MAAMe,OAAOA,CAACC,OAAsB,EAAuC;IACzE,IAAI,IAAI,CAACT,QAAQ,EAAE,OAAO,IAAI,CAACA,QAAQ;IACvC,IAAIN,OAAe;IACnB,IAAI;MACFA,OAAO,GAAGH,qBAAqB,CAACkB,OAAO,CAAC;IAC1C,CAAC,CAAC,MAAM;MACN,IAAI,CAAC,IAAI,CAAChB,OAAO,EAAE;QACjB,IAAI,CAACA,OAAO,GAAGJ,YAAY,CAAC,CAAC;QAC7B,IAAI,CAACiB,IAAI,CAAC,CAAC;MACb;MACA,OAAO,IAAI,CAACb,OAAO;IACrB;IACA,IAAI,CAACO,QAAQ,GAAG,CAAC,YAAY;MAC3B,IAAI;QACF,MAAMU,MAAM,GAAG,IAAIvB,aAAa,CAACsB,OAAO,CAAC;QACzC,MAAME,EAAE,GAAG,MAAMD,MAAM,CAACC,EAAE,CAAC,CAAC;QAC5B,IAAI,CAAClB,OAAO,GAAGD,sBAAsB,CAACmB,EAAE,EAAEjB,OAAO,CAAC;QAClD,IAAI,CAACY,IAAI,CAAC,CAAC;QACX,OAAO,IAAI,CAACb,OAAO;MACrB,CAAC,CAAC,MAAM;QACN,IAAI,CAAC,IAAI,CAACA,OAAO,EAAE;UACjB,IAAI,CAACA,OAAO,GAAGJ,YAAY,CAAC,CAAC;UAC7B,IAAI,CAACiB,IAAI,CAAC,CAAC;QACb;QACA,OAAO,IAAI,CAACb,OAAO;MACrB,CAAC,SAAS;QACR,IAAI,CAACO,QAAQ,GAAG,IAAI;MACtB;IACF,CAAC,EAAE,CAAC;IACJ,OAAO,IAAI,CAACA,QAAQ;EACtB;EAEAL,YAAYA,CAAA,EAAqB;IAC/B,OAAO,IAAI,CAACF,OAAO,EAAEE,YAAY,IAAI;MAAE,GAAGP;IAAqB,CAAC;EAClE;EAEAwB,IAAIA,CAAA,EAAe;IACjB,OAAO,IAAI,CAACnB,OAAO,EAAEmB,IAAI,IAAI,MAAM;EACrC;AACF;AAEA,OAAO,MAAMC,YAAY,GAAG,IAAIhB,gBAAgB,CAAC,CAAC","ignoreList":[]}

package/lib/module/commercial/AgentDebug.js

@@ -0,0 +1,99 @@
+"use strict";
+
+import { resolveDebugLogging } from "./devMode.js";
+import { extractAffordances } from "../privacy/screenModel.js";
+import { HostActionsStore } from "../host/HostActions.js";
+/**
+ * Developer-facing logs: what the SDK observed in the host App
+ * (controls / fields / actions). Never logs security policy internals.
+ */
+export const AgentDebug = {
+  enabled(config) {
+    return resolveDebugLogging(config);
+  },
+  /** High-level run lifecycle (goal only, no policy). */
+  runStart(config, goal) {
+    if (!resolveDebugLogging(config)) return;
+    // eslint-disable-next-line no-console
+    console.log('[koko] 开始任务:', goal.slice(0, 120));
+  },
+  runEnd(config, summary, ok) {
+    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, cap) {
+    if (!resolveDebugLogging(config)) return;
+    // eslint-disable-next-line no-console
+    console.warn(`[koko] 视图树在 maxDepth=${cap} 处被截断，页面正文可能完全缺失（只剩外层导航）。` + '请调大 dumpMaxDepth。');
+  },
+  /** Capabilities discovered on the current screen. */
+  screenCapabilities(config, tree) {
+    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, step, tool, detail) {
+    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, message) {
+    if (!resolveDebugLogging(config)) return;
+    const safe = sanitizeDevMessage(message);
+    // eslint-disable-next-line no-console
+    console.warn('[koko] 任务遇到问题:', safe);
+  }
+};
+function formatAffordance(a) {
+  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, detail) {
+  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) {
+  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);
+}
+//# sourceMappingURL=AgentDebug.js.map

package/lib/module/commercial/AgentDebug.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["resolveDebugLogging","extractAffordances","HostActionsStore","AgentDebug","enabled","config","runStart","goal","console","log","slice","runEnd","summary","ok","dumpTruncated","cap","warn","screenCapabilities","tree","items","host","getActions","length","lines","map","formatAffordance","a","label","testID","join","appAction","step","tool","detail","actionLabel","runIssue","message","safe","sanitizeDevMessage","kind","near","d","trim","lower","toLowerCase","test"],"sourceRoot":"../../../src","sources":["commercial/AgentDebug.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/commercial/ExecutionGuard.js

@@ -0,0 +1,49 @@
+"use strict";
+
+/**
+ * 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.
+ */
+
+function peekExp(permit) {
+  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);
+    return typeof payload.exp === 'number' ? payload.exp : null;
+  } catch {
+    return null;
+  }
+}
+class ExecutionGuardImpl {
+  permit = null;
+  sessionId = null;
+  setPermit(permit, sessionId) {
+    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) {
+    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();
+//# sourceMappingURL=ExecutionGuard.js.map

package/lib/module/commercial/ExecutionGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["peekExp","permit","payloadB64","split","pad","length","repeat","json","globalThis","atob","replace","Buffer","from","toString","payload","JSON","parse","exp","ExecutionGuardImpl","sessionId","setPermit","undefined","getPermit","getSessionId","clear","assert","action","Error","Math","floor","Date","now","ExecutionGuard"],"sourceRoot":"../../../src","sources":["commercial/ExecutionGuard.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;;AAIA,SAASA,OAAOA,CAACC,MAAc,EAAiB;EAC9C,IAAI;IACF,MAAM,CAACC,UAAU,CAAC,GAAGD,MAAM,CAACE,KAAK,CAAC,GAAG,CAAC;IACtC,IAAI,CAACD,UAAU,EAAE,OAAO,IAAI;IAC5B,MAAME,GAAG,GACPF,UAAU,CAACG,MAAM,GAAG,CAAC,KAAK,CAAC,GACvB,EAAE,GACF,GAAG,CAACC,MAAM,CAAC,CAAC,GAAIJ,UAAU,CAACG,MAAM,GAAG,CAAE,CAAC;IAC7C,MAAME,IAAI,GAAGC,UAAU,CAACC,IAAI,GACxBD,UAAU,CAACC,IAAI,CAACP,UAAU,CAACQ,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAACA,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAGN,GAAG,CAAC,GACvEO,MAAM,CAACC,IAAI,CACTV,UAAU,CAACQ,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAACA,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAGN,GAAG,EACtD,QACF,CAAC,CAACS,QAAQ,CAAC,MAAM,CAAC;IACtB,MAAMC,OAAO,GAAGC,IAAI,CAACC,KAAK,CAACT,IAAI,CAAqB;IACpD,OAAO,OAAOO,OAAO,CAACG,GAAG,KAAK,QAAQ,GAAGH,OAAO,CAACG,GAAG,GAAG,IAAI;EAC7D,CAAC,CAAC,MAAM;IACN,OAAO,IAAI;EACb;AACF;AAEA,MAAMC,kBAAkB,CAAC;EACfjB,MAAM,GAAkB,IAAI;EAC5BkB,SAAS,GAAkB,IAAI;EAEvCC,SAASA,CAACnB,MAAqB,EAAEkB,SAAyB,EAAE;IAC1D,IAAI,CAAClB,MAAM,GAAGA,MAAM;IACpB,IAAIkB,SAAS,KAAKE,SAAS,EAAE,IAAI,CAACF,SAAS,GAAGA,SAAS;EACzD;EAEAG,SAASA,CAAA,EAAG;IACV,OAAO,IAAI,CAACrB,MAAM;EACpB;EAEAsB,YAAYA,CAAA,EAAG;IACb,OAAO,IAAI,CAACJ,SAAS;EACvB;EAEAK,KAAKA,CAAA,EAAG;IACN,IAAI,CAACvB,MAAM,GAAG,IAAI;IAClB,IAAI,CAACkB,SAAS,GAAG,IAAI;EACvB;EAEAM,MAAMA,CAACC,MAAqB,EAAE;IAC5B,IAAI,CAAC,IAAI,CAACzB,MAAM,EAAE;MAChB,MAAM,IAAI0B,KAAK,CACb,cAAcD,MAAM,4DACtB,CAAC;IACH;IACA,MAAMT,GAAG,GAAGjB,OAAO,CAAC,IAAI,CAACC,MAAM,CAAC;IAChC,IAAIgB,GAAG,IAAI,IAAI,IAAIA,GAAG,GAAGW,IAAI,CAACC,KAAK,CAACC,IAAI,CAACC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE;MACtD,MAAM,IAAIJ,KAAK,CACb,uCAAuCD,MAAM,8BAC/C,CAAC;IACH;EACF;AACF;AAEA,OAAO,MAAMM,cAAc,GAAG,IAAId,kBAAkB,CAAC,CAAC","ignoreList":[]}

package/lib/module/commercial/UsageBus.js

@@ -0,0 +1,38 @@
+"use strict";
+
+/**
+ * Fan-out for usage / lifecycle events. Host `onUsageEvent` is wired here.
+ * Never used to gate execution.
+ */
+class UsageBusImpl {
+  listeners = new Set();
+  recent = [];
+  maxRecent = 100;
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  emit(event) {
+    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() {
+    return [...this.recent];
+  }
+  clear() {
+    this.recent = [];
+  }
+}
+export const UsageBus = new UsageBusImpl();
+//# sourceMappingURL=UsageBus.js.map

package/lib/module/commercial/UsageBus.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["UsageBusImpl","listeners","Set","recent","maxRecent","subscribe","listener","add","delete","emit","event","push","length","splice","l","getRecent","clear","UsageBus"],"sourceRoot":"../../../src","sources":["commercial/UsageBus.ts"],"mappings":";;AAIA;AACA;AACA;AACA;AACA,MAAMA,YAAY,CAAC;EACTC,SAAS,GAAG,IAAIC,GAAG,CAAW,CAAC;EAC/BC,MAAM,GAAqB,EAAE;EACpBC,SAAS,GAAG,GAAG;EAEhCC,SAASA,CAACC,QAAkB,EAAc;IACxC,IAAI,CAACL,SAAS,CAACM,GAAG,CAACD,QAAQ,CAAC;IAC5B,OAAO,MAAM;MACX,IAAI,CAACL,SAAS,CAACO,MAAM,CAACF,QAAQ,CAAC;IACjC,CAAC;EACH;EAEAG,IAAIA,CAACC,KAAqB,EAAE;IAC1B,IAAI,CAACP,MAAM,CAACQ,IAAI,CAACD,KAAK,CAAC;IACvB,IAAI,IAAI,CAACP,MAAM,CAACS,MAAM,GAAG,IAAI,CAACR,SAAS,EAAE;MACvC,IAAI,CAACD,MAAM,CAACU,MAAM,CAAC,CAAC,EAAE,IAAI,CAACV,MAAM,CAACS,MAAM,GAAG,IAAI,CAACR,SAAS,CAAC;IAC5D;IACA,KAAK,MAAMU,CAAC,IAAI,IAAI,CAACb,SAAS,EAAE;MAC9B,IAAI;QACFa,CAAC,CAACJ,KAAK,CAAC;MACV,CAAC,CAAC,MAAM;QACN;MAAA;IAEJ;EACF;EAEAK,SAASA,CAAA,EAAqB;IAC5B,OAAO,CAAC,GAAG,IAAI,CAACZ,MAAM,CAAC;EACzB;EAEAa,KAAKA,CAAA,EAAG;IACN,IAAI,CAACb,MAAM,GAAG,EAAE;EAClB;AACF;AAEA,OAAO,MAAMc,QAAQ,GAAG,IAAIjB,YAAY,CAAC,CAAC","ignoreList":[]}