@aiscene/shared 8.0.3 → 8.0.4

package/src/agent-tools/tool-defaults.ts

@@ -0,0 +1,119 @@
+/**
+ * Unified, declarative mechanism for "force a default option on every tool
+ * call" behaviors exposed by device and Agent Skill CLIs.
+ *
+ * Adding a new behavior flag (e.g. `--deep-search`) is a one-line change to
+ * {@link TOOL_BEHAVIOR_FLAGS}: declare which default-option "bag" it fills.
+ * The tool generator, tools managers and CLI parsing are all generic
+ * over {@link ToolDefaults} and never need to learn about individual flags.
+ *
+ * See https://github.com/web-infra-dev/midscene/issues/2446.
+ */
+
+/**
+ * Default options injected into generated tool calls. Each field is an
+ * injection point; an explicit per-call value always wins over these defaults.
+ */
+export interface ToolDefaults {
+  /**
+   * Merged into every locate field of action tools (`Tap`, `Input`, ...).
+   * e.g. `{ deepLocate: true }`.
+   */
+  locate?: Record<string, unknown>;
+  /**
+   * Merged into the `aiAction` options used by the `act` tool.
+   * e.g. `{ deepLocate: true, deepThink: true }`.
+   */
+  act?: Record<string, unknown>;
+}
+
+export interface ToolBehaviorFlag {
+  /** Kebab-case CLI flag name, e.g. `deep-locate` (exposed as `--deep-locate`). */
+  cli: string;
+  /** One-line description for help output. */
+  description: string;
+  /** Default-option bags this flag turns on when present. */
+  defaults: ToolDefaults;
+}
+
+/**
+ * The single source of truth for behavior flags. Add a row to support a new
+ * `--flag`; nothing else in the pipeline needs to change.
+ */
+export const TOOL_BEHAVIOR_FLAGS: readonly ToolBehaviorFlag[] = [
+  {
+    cli: 'deep-locate',
+    description:
+      'Force deep locate for every locating operation (better precision for small/ambiguous targets, a bit slower).',
+    defaults: { locate: { deepLocate: true }, act: { deepLocate: true } },
+  },
+  {
+    cli: 'deep-think',
+    description:
+      'Plan the act tool with deep thinking (richer context and sub-goal decomposition, a bit slower).',
+    defaults: { act: { deepThink: true } },
+  },
+];
+
+/** Merge two {@link ToolDefaults}, with `b` taking precedence over `a`. */
+export function mergeToolDefaults(
+  a: ToolDefaults,
+  b: ToolDefaults,
+): ToolDefaults {
+  const locate = { ...a.locate, ...b.locate };
+  const act = { ...a.act, ...b.act };
+  const result: ToolDefaults = {};
+  if (Object.keys(locate).length > 0) {
+    result.locate = locate;
+  }
+  if (Object.keys(act).length > 0) {
+    result.act = act;
+  }
+  return result;
+}
+
+/**
+ * Resolve the active {@link ToolDefaults} from a predicate that says whether a
+ * given flag (by its `cli` name) is enabled.
+ */
+export function resolveToolDefaults(
+  isEnabled: (cli: string) => boolean,
+): ToolDefaults {
+  return TOOL_BEHAVIOR_FLAGS.reduce<ToolDefaults>(
+    (acc, flag) =>
+      isEnabled(flag.cli) ? mergeToolDefaults(acc, flag.defaults) : acc,
+    {},
+  );
+}
+
+/**
+ * Split argv into the resolved {@link ToolDefaults} and the remaining args.
+ *
+ * Behavior flags (e.g. `--deep-locate`) are global: they may appear anywhere
+ * in argv and are not tied to a specific sub-command. They are recognized by
+ * exact kebab-case match and removed so a strict per-command parser never sees them. Every other
+ * token is returned untouched and in order for that per-command parser.
+ *
+ * This is the single place that knows how a behavior flag looks on the command
+ * line; the device / Agent Skill CLI resolves defaults from
+ * {@link TOOL_BEHAVIOR_FLAGS} through here / {@link resolveToolDefaults}.
+ */
+export function stripBehaviorFlags(argv: readonly string[]): {
+  rawArgs: string[];
+  toolDefaults: ToolDefaults;
+} {
+  const enabled = new Set<string>();
+  const rawArgs: string[] = [];
+  for (const arg of argv) {
+    const flag = TOOL_BEHAVIOR_FLAGS.find((f) => arg === `--${f.cli}`);
+    if (flag) {
+      enabled.add(flag.cli);
+    } else {
+      rawArgs.push(arg);
+    }
+  }
+  return {
+    rawArgs,
+    toolDefaults: resolveToolDefaults((cli) => enabled.has(cli)),
+  };
+}