@intentcomputing/koko-agent-sdk 1.0.1

package/src/client/GatewayClient.ts

@@ -0,0 +1,439 @@
+import { AppUserGateStore } from '../privacy/userGate';
+import type { AgentAction, Point, Selector } from '../types';
+import type { KokoAccountSnapshot, KokoEntitlements, KokoPlanId } from '../types';
+import { isAllowedGatewayUrl } from '../commercial/trust';
+import { allowLocalGatewayForDebugClient } from '../commercial/devMode';
+import { NativeBridge } from '../native/NativeBridge';
+import { sensitiveScreenKind, SensitiveScreenError } from '../privacy/sensitiveScreen';
+import { redactOutbound, redactViewTreeClient, viewTreeOutline } from '../privacy/redact';
+import { extractAffordances, screenModelText } from '../privacy/screenModel';
+import { buildOnDeviceAssistSync } from '../assist/OnDeviceAssist';
+import { HostActionsStore, filterVisibleHostActions, hostActionsModelText } from '../host/HostActions';
+import { ExplorationGraph, exploreHintsModelText, goalExploreQuery } from '../explore/ExplorationGraph';
+import { findNodeById } from '../selector/match';
+import { goalOcrCandidates, visibleWebViewFrames, PUBLIC_WALLET_CHOICES, walletConnectionAllowed } from '../assist/ocrTarget';
+import type { ViewNode } from '../types';
+
+export type GatewayConfig = {
+  /**
+   * Official gateway origin. Defaults to https://sdk.intentcomputing.net
+   * Localhost only in Metro debug clients (lab dogfood), not customer self-host.
+   */
+  baseUrl?: string;
+  /**
+   * App / member token from your product backend or dashboard.
+   * Never an LLM API key — users never see model keys.
+   */
+  token: string;
+  /**
+   * Host App ID (iOS bundle id / Android package name).
+   * Defaults to the native module's hostAppId. Must match the App ID bound to the token.
+   */
+  appId?: string;
+};
+
+const DEFAULT_GATEWAY = 'https://sdk.intentcomputing.net';
+
+export function resolveGatewayBaseUrl(cfg: GatewayConfig): string {
+  const raw = (cfg.baseUrl?.trim() || DEFAULT_GATEWAY).replace(/\/$/, '');
+  const check = isAllowedGatewayUrl(raw, allowLocalGatewayForDebugClient());
+  if (!check.ok) {
+    throw new Error(`KokoAgent: ${check.reason}`);
+  }
+  return raw;
+}
+
+export type AgentHistoryItem = {
+  tool: string;
+  args?: Record<string, unknown>;
+  result: string;
+  ok?: boolean;
+};
+
+export type GatewayNextRequest = {
+  session_id?: string;
+  goal: string;
+  ui_tree?: unknown;
+  ui_outline?: string;
+  ui_screen_model?: string;
+  /** Local-only evidence; gateway serializes only labels derived from goal. */
+  local_ocr_goal_labels?: string[];
+  local_ocr_wallet_choices?: string[];
+  local_web_wallet_aliases?: string[];
+  history: AgentHistoryItem[];
+  locale?: string;
+  user_reply?: string;
+  platform?: 'ios' | 'android' | 'unknown';
+};
+
+/** Build hints from the same redacted tree that crosses the upload boundary. */
+export function safePlannerModel(tree: ViewNode, goal: string, localOcrGoalLabels: string[] = [], localWalletChoices: string[] = [], hostWalletAliases: string[] = []): string {
+  const affordances = extractAffordances(tree, 80);
+  const labels = affordances.map(a => a.label);
+  const hosts = filterVisibleHostActions(HostActionsStore.getActions(), tree).flatMap(action => {
+    const visible = affordances.find(a => {
+      if (action.testID) return findNodeById(tree, a.nodeId)?.testID === action.testID;
+      return [action.label, action.text, ...(action.aliases || [])].some(label => label === a.label);
+    });
+    if (!visible) return [];
+    const kind = ['button', 'tab', 'nav', 'field', 'sheet', 'other'].includes(action.kind || '') ? action.kind : 'button';
+    return [{ ...action, kind, label: visible.label, text: visible.label, testID: findNodeById(tree, visible.nodeId)?.testID, aliases: [] }];
+  });
+  const possibleHints = ExplorationGraph.hintLabelsTowardGoal(labels, goalExploreQuery(goal).targetTokens, 6);
+  // Historical pages may contain data no longer visible. Only the current
+  // screen's exact public labels may be carried into the request.
+  const hints = possibleHints.filter(hint => labels.includes(hint));
+  const assist = buildOnDeviceAssistSync(goal, tree);
+  const allowedLabels = new Set(goalOcrCandidates(goal));
+  const verified = visibleWebViewFrames(tree).length && Array.isArray(localOcrGoalLabels)
+    ? [...new Set(localOcrGoalLabels)].filter(label => typeof label === 'string' && allowedLabels.has(label)).slice(0, 6) : [];
+  const ocrHints = verified.map(label =>
+    `- [local-ocr] A visible web text matched the goal-derived label 「${label}」 on this device. ` +
+    'Use find with one text rule to confirm it. When the user requested an action, its returned nodeId can be used to tap. No raw OCR text is included.',
+  ).join('\n');
+  const allowedChoices = new Set<string>(PUBLIC_WALLET_CHOICES);
+  const choices = visibleWebViewFrames(tree).length && walletConnectionAllowed(goal) && Array.isArray(localWalletChoices)
+    ? [...new Set(localWalletChoices)].filter(label => allowedChoices.has(label)).slice(0, 8) : [];
+  const choiceHint = choices.length >= 2
+    ? `- [local-wallet-choices] Visible public wallet options verified on-device: ${choices.join(', ')}. Use find with the exact option label; actual authorization stays with the user.`
+    : '';
+  const aliases = Array.isArray(hostWalletAliases) ? hostWalletAliases.filter(label => choices.includes(label)) : [];
+  const aliasHint = aliases.length ? `- [host-wallet-alias] Host confirms its injected wallet appears as: ${aliases.join(', ')}. Select that visible option for the host wallet.` : '';
+  const unavailableHint = choices.length >= 2 && hostWalletAliases.length && !aliases.length
+    ? '- [host-wallet-unavailable] None of the visible options matches the host wallet. Do not select a different wallet. If the host browser offers a desktop-site mode, try it and recheck the wallet chooser; otherwise report the unavailable option.' : '';
+  const extras = [hostActionsModelText(hosts), exploreHintsModelText(hints), assist.modelText, ocrHints, choiceHint, aliasHint, unavailableHint].filter(Boolean).join('\n');
+  return screenModelText(tree, 40, extras || undefined);
+}
+
+export type GatewayAction =
+  | { tool: 'dump'; args?: { reason?: string } }
+  | { tool: 'find'; args: { match: Array<Record<string, unknown>>; index?: number } }
+  | {
+      tool: 'tap';
+      args: {
+        selector?: Selector;
+        nodeId?: string;
+        /** Last-resort window point when the control is visible but not in the tree. */
+        point?: Point;
+        label?: string;
+      };
+    }
+  | {
+      tool: 'swipe';
+      args: { from: Point; to: Point; label?: string };
+    }
+  | {
+      tool: 'pinch';
+      args: { center: Point; scale: number; label?: string };
+    }
+  | {
+      tool: 'type';
+      args: {
+        text: string;
+        selector?: Selector;
+        nodeId?: string;
+        clear?: boolean;
+        label?: string;
+      };
+    }
+  | { tool: 'ask_user'; args: { question: string } }
+  | { tool: 'done'; args: { success: boolean; summary: string } };
+
+export type GatewayNextResponse = {
+  ok: true;
+  session_id: string;
+  narration: string | null;
+  action: GatewayAction;
+  provider: string;
+  model: string;
+  step: number;
+  region: string;
+  execution_permit: string;
+};
+
+export type GatewaySessionResponse = {
+  ok: true;
+  session_id: string;
+  execution_permit: string;
+};
+
+export class GatewayError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly quota?: KokoAccountSnapshot['quota'];
+  readonly plan?: KokoPlanId;
+
+  constructor(
+    message: string,
+    opts: {
+      code: string;
+      status: number;
+      quota?: KokoAccountSnapshot['quota'];
+      plan?: KokoPlanId;
+    },
+  ) {
+    super(message);
+    this.name = 'GatewayError';
+    this.code = opts.code;
+    this.status = opts.status;
+    this.quota = opts.quota;
+    this.plan = opts.plan;
+  }
+}
+
+export class GatewayClient {
+  private readonly baseUrl: string;
+  private readonly token: string;
+  private readonly appId: string;
+
+  constructor(cfg: GatewayConfig) {
+    this.baseUrl = resolveGatewayBaseUrl(cfg);
+    this.token = cfg.token;
+    this.appId = (cfg.appId?.trim() || NativeBridge.hostAppId() || '').trim();
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  getAppId(): string {
+    return this.appId;
+  }
+
+  private authHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.token}`,
+      'Content-Type': 'application/json',
+    };
+    if (this.appId) headers['X-Koko-App-Id'] = this.appId;
+    return headers;
+  }
+
+  private async parseError(res: Response, fallback: string): Promise<never> {
+    let json: {
+      error?: string;
+      message?: string;
+      quota?: KokoAccountSnapshot['quota'];
+      plan?: KokoPlanId;
+    } = {};
+    try {
+      json = (await res.json()) as typeof json;
+    } catch {
+      // ignore
+    }
+    throw new GatewayError(json.message || json.error || fallback, {
+      code: json.error || 'error',
+      status: res.status,
+      quota: json.quota,
+      plan: json.plan,
+    });
+  }
+
+  async health(): Promise<Record<string, unknown>> {
+    const res = await fetch(`${this.baseUrl}/v1/health`);
+    if (!res.ok) throw new Error(`health ${res.status}`);
+    return (await res.json()) as Record<string, unknown>;
+  }
+
+  /** Open session + initial execution permit (before first dump). */
+  async beginSession(sessionId?: string): Promise<GatewaySessionResponse> {
+    const res = await fetch(`${this.baseUrl}/v1/agent/session`, {
+      method: 'POST',
+      headers: this.authHeaders(),
+      body: JSON.stringify(sessionId ? { session_id: sessionId } : {}),
+    });
+    if (!res.ok) await this.parseError(res, `session ${res.status}`);
+    const json = (await res.json()) as GatewaySessionResponse;
+    if (!json.session_id || !json.execution_permit) {
+      throw new GatewayError('invalid session response', {
+        code: 'invalid_response',
+        status: res.status,
+      });
+    }
+    return {
+      ok: true,
+      session_id: json.session_id,
+      execution_permit: json.execution_permit,
+    };
+  }
+
+  async me(): Promise<KokoAccountSnapshot> {
+    const res = await fetch(`${this.baseUrl}/v1/me`, {
+      headers: this.authHeaders(),
+    });
+    const json = (await res.json()) as {
+      ok?: boolean;
+      plan?: string;
+      region?: string;
+      provider?: string;
+      entitlements?: Partial<KokoEntitlements>;
+      quota?: { daily?: number; used_today?: number; remaining?: number };
+      error?: string;
+      message?: string;
+    };
+    if (!res.ok) {
+      throw new GatewayError(json.message || json.error || `me ${res.status}`, {
+        code: json.error || 'unauthorized',
+        status: res.status,
+      });
+    }
+    const plan = (json.plan as KokoPlanId) || 'free';
+    const entitlements: KokoEntitlements = {
+      custom_branding: json.entitlements?.custom_branding === true,
+      locale: json.entitlements?.locale !== false,
+    };
+    const daily = json.quota?.daily ?? 0;
+    const used = json.quota?.used_today ?? 0;
+    return {
+      plan,
+      region: json.region,
+      provider: json.provider,
+      entitlements,
+      quota: {
+        daily,
+        used_today: used,
+        remaining: json.quota?.remaining ?? Math.max(0, daily - used),
+      },
+    };
+  }
+
+  async usage(limit = 50): Promise<{
+    quota: KokoAccountSnapshot['quota'];
+    plan: KokoPlanId;
+    events: unknown[];
+  }> {
+    const res = await fetch(`${this.baseUrl}/v1/usage?limit=${limit}`, {
+      headers: this.authHeaders(),
+    });
+    const json = (await res.json()) as {
+      ok?: boolean;
+      plan?: KokoPlanId;
+      quota?: KokoAccountSnapshot['quota'];
+      events?: unknown[];
+      error?: string;
+      message?: string;
+    };
+    if (!res.ok) {
+      throw new GatewayError(json.message || json.error || `usage ${res.status}`, {
+        code: json.error || 'error',
+        status: res.status,
+      });
+    }
+    return {
+      plan: json.plan || 'free',
+      quota: json.quota || { daily: 0, used_today: 0, remaining: 0 },
+      events: json.events || [],
+    };
+  }
+
+  async next(body: GatewayNextRequest): Promise<GatewayNextResponse> {
+    const supplied = body.ui_tree as ViewNode | undefined;
+    let live: ViewNode | undefined;
+    if (NativeBridge.isAvailable()) {
+      // Fail closed if the current screen cannot be checked. Never send a
+      // cached safe screen while a newly presented secret page is visible.
+      live = await NativeBridge.dump({ maxDepth: 100 });
+    }
+    const gate = AppUserGateStore.getHostGate();
+    if ((gate && ['recovery_phrase', 'private_key', 'password', 'pin', 'otp', 'secure_input'].includes(gate.kind)) ||
+        sensitiveScreenKind(live) || sensitiveScreenKind(supplied)) throw new SensitiveScreenError();
+    const safeTree = supplied ? redactViewTreeClient(supplied) : undefined;
+    const safeBody = redactOutbound({
+      session_id: body.session_id,
+      goal: body.goal,
+      history: body.history,
+      locale: body.locale,
+      user_reply: body.user_reply,
+      platform: body.platform,
+      ui_tree: safeTree,
+      // Build every visual hint from the redacted tree, never caller-provided
+      // model strings, unverified OCR text or historical off-screen labels.
+      ui_outline: safeTree ? viewTreeOutline(safeTree) : undefined,
+      ui_screen_model: safeTree ? safePlannerModel(safeTree, body.goal, body.local_ocr_goal_labels, body.local_ocr_wallet_choices, body.local_web_wallet_aliases) : undefined,
+    }, [live, supplied]);
+    const res = await fetch(`${this.baseUrl}/v1/agent/next`, {
+      method: 'POST',
+      headers: this.authHeaders(),
+      body: JSON.stringify(safeBody),
+    });
+    const json = (await res.json()) as
+      | GatewayNextResponse
+      | {
+          ok: false;
+          error: string;
+          message?: string;
+          quota?: KokoAccountSnapshot['quota'];
+          plan?: KokoPlanId;
+        };
+    if (!res.ok || !('ok' in json) || json.ok !== true) {
+      const err = json as {
+        error?: string;
+        message?: string;
+        quota?: KokoAccountSnapshot['quota'];
+        plan?: KokoPlanId;
+      };
+      throw new GatewayError(err.message || err.error || `gateway ${res.status}`, {
+        code: err.error || 'error',
+        status: res.status,
+        quota: err.quota,
+        plan: err.plan,
+      });
+    }
+    if (!json.execution_permit) {
+      throw new GatewayError('invalid agent response', {
+        code: 'invalid_response',
+        status: res.status,
+      });
+    }
+    return json;
+  }
+}
+
+export function toLocalAgentAction(action: GatewayAction): AgentAction | null {
+  switch (action.tool) {
+    case 'dump':
+      return { tool: 'dump' };
+    case 'find':
+      return {
+        tool: 'find',
+        args: {
+          selector: {
+            match: action.args.match as Selector['match'],
+            index: action.args.index,
+          },
+        },
+      };
+    case 'tap':
+      return {
+        tool: 'tap',
+        args: {
+          selector: action.args.selector,
+          nodeId: action.args.nodeId,
+          point: action.args.point,
+          options: undefined,
+        },
+      };
+    case 'swipe':
+      return {
+        tool: 'swipe',
+        args: { from: action.args.from, to: action.args.to },
+      };
+    case 'pinch':
+      return {
+        tool: 'pinch',
+        args: { center: action.args.center, scale: action.args.scale },
+      };
+    case 'type':
+      return {
+        tool: 'type',
+        args: {
+          text: action.args.text,
+          selector: action.args.selector,
+          nodeId: action.args.nodeId,
+          options: { clear: action.args.clear },
+        },
+      };
+    default:
+      return null;
+  }
+}

package/src/client/OperationReplayGuard.ts

@@ -0,0 +1,61 @@
+import type { GatewayAction } from './GatewayClient';
+import type { ViewNode } from '../types';
+import { find, findNodeById } from '../selector/match';
+import { sensitiveScreenKind } from '../privacy/sensitiveScreen';
+
+// Operation entries, not ordinary Next/Continue controls reused by wizards.
+const OPERATION = /创建|新建|添加|导入|备份|导出|提交|支付|转账|购买|删除|注销|\b(create|add|import|backup|back\s+up|export|submit|pay|transfer|buy|delete)\b/i;
+
+function hash(text: string): string {
+  let h = 2166136261;
+  for (const c of text) h = Math.imul(h ^ c.charCodeAt(0), 16777619);
+  return (h >>> 0).toString(16);
+}
+
+/** Keep only hashes of prior public operation entries across privacy purges. */
+export class OperationReplayGuard {
+  private attempts = new Set<string>();
+  hasHandoff = false;
+
+  reset() { this.attempts.clear(); this.hasHandoff = false; }
+  markHandoff() { this.hasHandoff = true; }
+
+  private key(action: GatewayAction, tree: ViewNode | null): string | null {
+    if (action.tool !== 'tap' || !tree || sensitiveScreenKind(tree)) return null;
+    const node = action.args.nodeId ? findNodeById(tree, action.args.nodeId) :
+      action.args.selector ? find(tree, action.args.selector) : null;
+    const selectorText = action.args.selector?.match.map(rule =>
+      'text' in rule ? rule.text : 'accessibilityLabel' in rule ? rule.accessibilityLabel : '',
+    ).filter(Boolean).join(' ');
+    const label = (node?.text || node?.accessibilityLabel || selectorText ||
+      action.args.label?.match(/[「“"]([^」”"]+)[」”"]/)?.[1] || action.args.label || '').trim();
+    if (!OPERATION.test(label)) return null;
+    // Public banners, prices and loading copy can change while the operation
+    // remains the same. Only an explicit host identity separates operations;
+    // native path IDs are snapshot-local and must not reset replay protection.
+    let identity = node?.testID || '';
+    if (node && !identity) {
+      const locate = (parent: ViewNode): boolean => {
+        for (const child of parent.children) {
+          if (child.id === node.id || locate(child)) {
+            if (!identity && parent.testID) identity = parent.testID;
+            return true;
+          }
+        }
+        return false;
+      };
+      locate(tree);
+    }
+    return hash(`${label.replace(/\s+/g, ' ').toLocaleLowerCase()}\n${identity}`);
+  }
+
+  record(action: GatewayAction, tree: ViewNode | null) {
+    const key = this.key(action, tree);
+    if (key) this.attempts.add(key);
+  }
+
+  blocks(action: GatewayAction, tree: ViewNode | null): boolean {
+    const key = this.key(action, tree);
+    return this.hasHandoff && !!key && this.attempts.has(key);
+  }
+}

package/src/client/RunCheckpoint.ts

@@ -0,0 +1,154 @@
+/**
+ * Survive a JS-context restart mid-run.
+ *
+ * Some actions destroy the runtime that is performing them: changing locale or
+ * theme, toggling RTL, flipping a feature flag, anything the host answers with
+ * a root remount or `reloadAsync`. The tap succeeds, the App comes back — but
+ * the `runGoal` promise, its session and the whole TaskStore died with the old
+ * context, so the caller can never learn the outcome.
+ *
+ * So checkpoint the goal to disk while it runs. On the next SDK init a fresh
+ * checkpoint means "we were interrupted", and the run can be picked up again
+ * from whatever screen the App came back on.
+ *
+ * Storage is best-effort: without AsyncStorage this degrades to memory, which
+ * cannot survive a reload. That is the same tradeoff ExplorationGraph makes —
+ * a missing optional peer must not break a run, only reduce it.
+ */
+
+type AsyncStorageLike = {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+};
+
+function tryAsyncStorage(): AsyncStorageLike | null {
+  try {
+    // Optional peer — many RN hosts already ship it.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('@react-native-async-storage/async-storage');
+    const store = mod?.default ?? mod;
+    if (store && typeof store.getItem === 'function') return store;
+  } catch {
+    // optional
+  }
+  return null;
+}
+
+const KEY = 'koko.run.checkpoint.v1';
+
+/**
+ * A reload takes a second or two. Anything older than this was not an
+ * interruption — it is a run that died for some other reason (force quit,
+ * crash, the user walking away), and silently driving the UI on next launch
+ * would be surprising rather than helpful.
+ */
+export const RESUME_MAX_AGE_MS = 90_000;
+
+/**
+ * One resume per goal. If the goal itself is what reloads the App, resuming it
+ * reloads again; without a cap that is an infinite loop across launches.
+ */
+export const RESUME_MAX_ATTEMPTS = 1;
+
+export type RunCheckpointData = {
+  goal: string;
+  startedAt: number;
+  /** Bumped per step, so age reflects liveness rather than run length. */
+  updatedAt: number;
+  /** Resumes already spent on this goal. */
+  resumes: number;
+};
+
+let memory: RunCheckpointData | null = null;
+// Storage implementations need not complete writes in invocation order. Keep
+// read/claim/write in one queue so an older clear cannot erase a newer run.
+let storageQueue: Promise<unknown> = Promise.resolve();
+function serialized<T>(operation: () => Promise<T>): Promise<T> {
+  const result = storageQueue.then(operation);
+  storageQueue = result.catch(() => {});
+  return result;
+}
+
+async function write(data: RunCheckpointData | null) {
+  memory = data;
+  const storage = tryAsyncStorage();
+  if (!storage) return;
+  try {
+    if (data) await storage.setItem(KEY, JSON.stringify(data));
+    else await storage.removeItem(KEY);
+  } catch {
+    // best-effort
+  }
+}
+
+async function read(): Promise<RunCheckpointData | null> {
+  const storage = tryAsyncStorage();
+  if (!storage) return memory;
+  try {
+    const raw = await storage.getItem(KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as RunCheckpointData;
+    if (!parsed || typeof parsed.goal !== 'string' || !parsed.goal) return null;
+    return {
+      goal: parsed.goal,
+      startedAt: Number(parsed.startedAt) || 0,
+      updatedAt: Number(parsed.updatedAt) || Number(parsed.startedAt) || 0,
+      resumes: Number(parsed.resumes) || 0,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export const RunCheckpoint = {
+  /** Mark a goal as in flight. `resumes` carries over when resuming. */
+  begin(goal: string, resumes = 0) {
+    return serialized(async () => {
+      const now = Date.now();
+      await write({ goal, startedAt: now, updatedAt: now, resumes });
+    });
+  },
+
+  /** Keep the checkpoint fresh while the loop makes progress. */
+  touch() {
+    return serialized(async () => {
+      if (!memory) return;
+      await write({ ...memory, updatedAt: Date.now() });
+    });
+  },
+
+  /** The run reached a verdict — nothing left to resume. */
+  clear() {
+    return serialized(async () => {
+      if (!memory && !tryAsyncStorage()) return;
+      await write(null);
+    });
+  },
+
+  /**
+   * Claim an interrupted run, if there is one worth resuming.
+   *
+   * Clears before returning: a resume that dies the same way must not be
+   * claimed again on the next launch.
+   */
+  async claimResumable(opts?: {
+    maxAgeMs?: number;
+    maxAttempts?: number;
+    now?: number;
+  }): Promise<RunCheckpointData | null> {
+    return serialized(async () => {
+      const maxAgeMs = opts?.maxAgeMs ?? RESUME_MAX_AGE_MS;
+      const maxAttempts = opts?.maxAttempts ?? RESUME_MAX_ATTEMPTS;
+      const now = opts?.now ?? Date.now();
+      const found = await read();
+      await write(null);
+      if (!found) return null;
+      if (found.resumes >= maxAttempts) return null;
+      if (!Number.isFinite(found.updatedAt) || !found.updatedAt ||
+          now < found.updatedAt || now - found.updatedAt > maxAgeMs ||
+          !Number.isFinite(found.resumes) || found.resumes < 0) return null;
+      return found;
+    });
+  },
+};