surf-cli 2.11.0 → 2.13.0

package/native/mcp-server.cjs

@@ -290,6 +290,16 @@ const TOOL_SCHEMAS = {
       timeout: z.number().optional().describe("Timeout in seconds")
     }
   },
+  kimi: {
+    desc: "Ask Kimi AI (kimi.com, Moonshot K-series) through the browser session",
+    schema: {
+      query: z.string().optional().describe("Question or prompt"),
+      model: z.string().optional().describe("Model: instant (default), thinking, high, or any label in kimi.com's picker"),
+      "with-page": z.boolean().optional().describe("Include current page context"),
+      timeout: z.number().optional().describe("Timeout in seconds"),
+      validate: z.boolean().optional().describe("Check kimi.com UI and list available models")
+    }
+  },
   "network.export": {
     desc: "Export captured network requests",
     schema: {

package/native/playbook-cli.cjs

@@ -48,7 +48,7 @@ function runSpec(argv) {
   const parsed = parseCommandArgs(argv.slice(offset));
   const [playbook, op] = parsed.positional;
   if (!playbook || !op) throw new Error(direct ? "Usage: surf use <playbook> <op> [--arg value]" : "Usage: surf pb run <playbook> <op> [--arg value]");
-  const reserved = new Set(["json", "no-lock", "tab-id", "write", "repeat", "retry-attempt", "override-in-doubt", "pin-built-in"]);
+  const reserved = new Set(["json", "no-lock", "tab-id", "write", "repeat", "retry-attempt", "override-in-doubt", "pin-built-in", "allow-script"]);
   const args = Object.fromEntries(Object.entries(parsed.options).filter(([name]) => !reserved.has(name)));
   return { playbook, op, args, options: parsed.options };
 }
@@ -89,6 +89,7 @@ async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
       retryAttempt: spec.options["retry-attempt"],
       overrideInDoubt: spec.options["override-in-doubt"] === true,
       pinBuiltIn: spec.options["pin-built-in"] === true,
+      allowScript: spec.options["allow-script"] === true,
     };
     const value = await requestHost(endpoint, "playbook.run", args, {
       tabId: spec.options["tab-id"],
@@ -98,7 +99,7 @@ async function handlePlaybookCli(argv, { endpoint, cwd = process.cwd() }) {
   }
   const command = argv[1];
   const parsed = parseCommandArgs(argv.slice(2));
-  if (!command || command === "help") return { handled: true, value: "Usage: surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>" };
+  if (!command || command === "help") return { handled: true, value: "Usage: surf playbook|pb <list|show|ops|run|record|suggest|save|client|trace|export|import>\nRun trusted script strategies with: surf use <playbook> <op> --allow-script" };
   if (endpoint?.kind === "remote" && ["list", "show", "ops"].includes(command)) throw new Error(`playbook ${command} is local-only with --remote because runs resolve on the browser host`);
   if (command === "list") return { handled: true, value: listPlaybooks({ cwd }), json: parsed.options.json === true };
   if (command === "show") {

package/native/playbook-runtime.cjs

@@ -1,4 +1,5 @@
-const { executeWorkflow } = require("./workflow-runtime.cjs");
+const { executeSingleStep, executeWorkflow } = require("./workflow-runtime.cjs");
+const { runWorkflowScript } = require("./workflow-script-runtime.cjs");
 
 function applyTemplate(value, args) {
   if (typeof value === "string") {
@@ -93,6 +94,31 @@ return { status: response.status, ok: response.ok, url: response.url, headers: O
 }
 
 async function runStrategy(strategy, context) {
+  if (strategy.using === "script") {
+    if (context.allowScript !== true) throw new Error("script strategy requires --allow-script");
+    const vars = { ...context.args };
+    const result = await runWorkflowScript({
+      script: strategy.script,
+      input: context.args,
+      timeoutMs: strategy.timeoutMs ?? 10 * 60 * 1000,
+      signal: context.signal,
+      onEvent: context.onEvent,
+      executeTool: async (tool, args, options = {}) => {
+        await context.markDispatched?.();
+        const step = await executeSingleStep({ cmd: tool, args, as: "value" }, vars, {
+          autoWait: strategy.autoWait !== false,
+          executeTool: context.executeTool,
+          onEvent: context.onEvent,
+          signal: options.signal || context.signal,
+          sleep: context.sleep,
+          stepDelay: strategy.stepDelay ?? 100,
+        });
+        if (!step.success) throw new Error(step.error || `tool ${tool} failed`);
+        return step.output;
+      },
+    });
+    return result.value;
+  }
   if (strategy.using === "workflow") {
     const result = await executeWorkflow(applyTemplate(strategy.steps, context.args), {
       autoWait: strategy.autoWait !== false,
@@ -130,7 +156,7 @@ async function runStrategy(strategy, context) {
   throw new Error(`unsupported strategy: ${strategy.using}`);
 }
 
-async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId, executeTool, executeNative, signal, sleep, onEvent = () => {}, beforeDispatch = async () => {}, afterDispatch = async () => {} }) {
+async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId, executeTool, executeNative, signal, sleep, onEvent = () => {}, beforeDispatch = async () => {}, afterDispatch = async () => {}, allowScript = false }) {
   const args = resolveArgs(op, providedArgs);
   const attempts = [];
   for (let index = 0; index < op.run.length; index++) {
@@ -154,6 +180,7 @@ async function runPlaybookOp({ playbook, op, args: providedArgs = {}, attemptId,
         allowedOrigins: op.origins || playbook.origins || [],
         markDispatched: op.effect === "write" ? markDispatched : undefined,
         serverIdempotency: op.effect === "write" ? op.safety?.serverIdempotency : undefined,
+        allowScript,
       });
       const value = extractResult(raw, strategy.extract);
       verifyResult(value, strategy.verify || strategy.expect || op.on?.success?.expect, raw);

package/native/playbooks.cjs

@@ -75,8 +75,21 @@ function validateWriteWorkflowSteps(steps, opId) {
   }
 }
 
+function normalizeScript(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.every((line) => typeof line === "string")) return value.join("\n");
+  return null;
+}
+
 function validateStrategy(strategy, effect, opId) {
   if (!strategy || typeof strategy !== "object" || Array.isArray(strategy)) throw new Error("playbook strategy must be an object");
+  if (strategy.using === "script") {
+    if (effect === "write") throw new Error(`write op ${opId} script strategy is not supported`);
+    const script = normalizeScript(strategy.script);
+    if (!script?.trim()) throw new Error("script strategy requires script");
+    if (strategy.timeoutMs !== undefined && (!Number.isInteger(strategy.timeoutMs) || strategy.timeoutMs < 1)) throw new Error("script strategy timeoutMs must be a positive integer");
+    return { ...strategy, script };
+  }
   if (strategy.using === "workflow") {
     if (!Array.isArray(strategy.steps) || strategy.steps.length === 0) throw new Error("workflow strategy requires steps");
     const steps = strategy.steps.map(normalizeStep);

package/native/workflow-definition.cjs

@@ -7,6 +7,7 @@ const COMMANDS = {
   ai: { primaryArg: "query", effect: "read", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
   gemini: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
   chatgpt: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
+  kimi: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
   "oracle.ask": { primaryArg: "prompt", effect: "page-write", argKinds: { prompt: "user-input" }, sensitiveArgs: ["prompt"] },
   perplexity: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },
   grok: { primaryArg: "query", effect: "page-write", argKinds: { query: "user-input" }, sensitiveArgs: ["query"] },

package/native/workflow-script-runtime.cjs

@@ -0,0 +1,294 @@
+const { Worker } = require("node:worker_threads");
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+const WORKER_SOURCE = String.raw`
+const { parentPort } = require("node:worker_threads");
+const vm = require("node:vm");
+const { inspect } = require("node:util");
+
+let nextCallId = 0;
+const pending = new Map();
+const keyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const fingerprints = new Map();
+let contextObjectPrototype;
+
+function stableJson(value) {
+  if (Array.isArray(value)) return "[" + value.map(stableJson).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.keys(value).sort().map((key) => JSON.stringify(key) + ":" + stableJson(value[key])).join(",") + "}";
+  return JSON.stringify(value) ?? "undefined";
+}
+
+function assertJsonValue(value, path = "value", seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(path + " must contain only finite JSON numbers.");
+    return;
+  }
+  if (typeof value !== "object") throw new Error(path + " must be a JSON value; received " + typeof value + ".");
+  if (seen.has(value)) throw new Error(path + " must not contain cycles.");
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(value, index)) throw new Error(path + " must not contain sparse array entries.");
+      assertJsonValue(value[index], path + "[" + index + "]", seen);
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype && prototype !== contextObjectPrototype) throw new Error(path + " must contain only plain JSON objects.");
+    if (Object.getOwnPropertySymbols(value).length > 0) throw new Error(path + " must not contain symbol keys.");
+    for (const [key, entry] of Object.entries(value)) assertJsonValue(entry, path + "." + key, seen);
+  }
+  seen.delete(value);
+}
+
+function hostCall(method, args) {
+  return new Promise((resolve, reject) => {
+    const callId = ++nextCallId;
+    pending.set(callId, { resolve, reject });
+    parentPort.postMessage({ type: "call", callId, method, args });
+  });
+}
+
+function validateRunCall(key, params, label, nextFingerprints = fingerprints) {
+  if (typeof key !== "string" || !keyPattern.test(key)) throw new Error(label + " has an invalid key.");
+  if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error(label + " requires a params object.");
+  const tool = params.tool ?? params.cmd;
+  if (typeof tool !== "string" || !tool) throw new Error(label + " requires a tool string.");
+  if (params.args !== undefined && (!params.args || typeof params.args !== "object" || Array.isArray(params.args))) throw new Error(label + " args must be an object.");
+  assertJsonValue(params, label + " params");
+  const fingerprint = stableJson(params);
+  const existing = nextFingerprints.get(key);
+  if (existing !== undefined && existing !== fingerprint) throw new Error("Duplicate script key '" + key + "' used with incompatible tool params.");
+  nextFingerprints.set(key, fingerprint);
+}
+
+const tools = Object.freeze({
+  run(key, params) {
+    validateRunCall(key, params, "tools.run");
+    return hostCall("run", { key, params });
+  },
+  all(items) {
+    if (!Array.isArray(items)) throw new Error("tools.all(items) requires an array.");
+    const nextFingerprints = new Map(fingerprints);
+    const calls = [];
+    for (let index = 0; index < items.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(items, index)) throw new Error("tools.all items must not contain sparse entries.");
+      const item = items[index];
+      if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("tools.all item " + index + " must be an object.");
+      const { key, ...params } = item;
+      validateRunCall(key, params, "tools.all item " + index, nextFingerprints);
+      calls.push({ key, params });
+    }
+    for (const { key, params } of calls) fingerprints.set(key, stableJson(params));
+    return Promise.all(calls.map(({ key, params }) => hostCall("run", { key, params, collectFailure: true })));
+  },
+  ref(result) {
+    if (!result || typeof result !== "object") throw new Error("tools.ref(result) requires a tool result object.");
+    return "[tool " + (result.key || "unknown") + "]";
+  },
+  refs(results) {
+    if (!Array.isArray(results)) throw new Error("tools.refs(results) requires an array.");
+    return results.map(tools.ref).join("\n");
+  },
+});
+
+const capturedConsole = Object.freeze(Object.fromEntries(
+  ["log", "info", "warn", "error"].map((level) => [level, (...args) => {
+    parentPort.postMessage({ type: "console", level, text: args.map((value) => typeof value === "string" ? value : inspect(value, { depth: 4, breakLength: 120 })).join(" ") });
+  }]),
+));
+
+parentPort.on("message", async (message) => {
+  if (message.type === "response") {
+    const entry = pending.get(message.callId);
+    if (!entry) return;
+    pending.delete(message.callId);
+    if (message.ok) entry.resolve(message.value);
+    else entry.reject(new Error(message.error));
+    return;
+  }
+  if (message.type !== "start") return;
+  try {
+    const sandbox = {
+      input: Object.freeze(message.input ?? {}),
+      tools,
+      surf: tools,
+      emit(value) { assertJsonValue(value, "emit"); parentPort.postMessage({ type: "emit", value }); },
+      console: capturedConsole,
+    };
+    const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
+    contextObjectPrototype = vm.runInContext("Object.prototype", context);
+    const compiled = new vm.Script("(async () => {\n" + message.script + "\n})()", { filename: "surf-workflow-script.js" });
+    const value = await compiled.runInContext(context);
+    const persistedValue = value === undefined ? null : value;
+    assertJsonValue(persistedValue, "return");
+    parentPort.postMessage({ type: "complete", value: persistedValue });
+  } catch (error) {
+    parentPort.postMessage({ type: "error", error: error && error.stack ? error.stack : String(error) });
+  }
+});
+`;
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertJsonValue(value, path = "value", seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${path} must contain only finite JSON numbers.`);
+    return;
+  }
+  if (typeof value !== "object") throw new Error(`${path} must be a JSON value; received ${typeof value}.`);
+  if (seen.has(value)) throw new Error(`${path} must not contain cycles.`);
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      if (!Object.hasOwn(value, index)) throw new Error(`${path} must not contain sparse array entries.`);
+      assertJsonValue(value[index], `${path}[${index}]`, seen);
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype) throw new Error(`${path} must contain only plain JSON objects.`);
+    if (Object.getOwnPropertySymbols(value).length > 0) throw new Error(`${path} must not contain symbol keys.`);
+    for (const [key, entry] of Object.entries(value)) assertJsonValue(entry, `${path}.${key}`, seen);
+  }
+  seen.delete(value);
+}
+
+function omitUndefined(value, seen = new Set()) {
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return value;
+  seen.add(value);
+  const next = Array.isArray(value)
+    ? value.map((entry) => entry === undefined ? null : omitUndefined(entry, seen))
+    : Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => entry === undefined ? [] : [[key, omitUndefined(entry, seen)]]));
+  seen.delete(value);
+  return next;
+}
+
+function validateKey(value) {
+  if (typeof value !== "string" || !KEY_PATTERN.test(value)) {
+    throw new Error("tool key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+  }
+  return value;
+}
+
+async function runWorkflowScript({ script, input = {}, timeoutMs = 10 * 60 * 1000, signal, executeTool, onEvent = () => {}, onEmit = () => {}, onConsole = () => {} }) {
+  if (typeof script !== "string" || !script.trim()) throw new Error("script strategy requires a non-empty script string");
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1) throw new Error("script timeoutMs must be a positive integer");
+  if (typeof executeTool !== "function") throw new Error("script strategy requires executeTool");
+  assertJsonValue(input, "input");
+
+  const worker = new Worker(WORKER_SOURCE, { eval: true });
+  const emits = [];
+  const consoleEntries = [];
+  const trace = [];
+  const childController = new AbortController();
+  let settled = false;
+
+  return await new Promise((resolve, reject) => {
+    const finish = (outcome) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      void worker.terminate();
+      childController.abort(outcome.error || new Error("Script strategy completed."));
+      if (outcome.error) reject(outcome.error);
+      else resolve({ value: outcome.value, emits, console: consoleEntries, trace });
+    };
+    const onAbort = () => finish({ error: new Error(signal.reason instanceof Error ? signal.reason.message : String(signal.reason || "Script strategy aborted")) });
+    const timer = setTimeout(() => finish({ error: new Error(`Script strategy timed out after ${timeoutMs}ms.`) }), timeoutMs);
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) return onAbort();
+
+    const respond = (callId, promise) => {
+      void promise.then(
+        (value) => {
+          try {
+            const clean = omitUndefined(value);
+            assertJsonValue(clean, "tool result");
+            worker.postMessage({ type: "response", callId, ok: true, value: clean });
+          } catch (error) {
+            worker.postMessage({ type: "response", callId, ok: false, error: error instanceof Error ? error.message : String(error) });
+          }
+        },
+        (error) => worker.postMessage({ type: "response", callId, ok: false, error: error instanceof Error ? error.message : String(error) }),
+      );
+    };
+
+    worker.on("error", (error) => finish({ error: new Error(`Script worker failed: ${error.message}`) }));
+    worker.on("exit", (code) => {
+      if (!settled && code !== 0) finish({ error: new Error(`Script worker exited with code ${code}.`) });
+    });
+    worker.on("message", (message) => {
+      if (message.type === "emit") {
+        try {
+          assertJsonValue(message.value, "emit");
+          emits.push(message.value);
+          onEmit([...emits]);
+        } catch (error) {
+          finish({ error: new Error(`Script emit could not be persisted: ${error.message}`) });
+        }
+        return;
+      }
+      if (message.type === "console") {
+        if (["log", "info", "warn", "error"].includes(message.level) && typeof message.text === "string") {
+          const entry = { level: message.level, text: message.text };
+          consoleEntries.push(entry);
+          onConsole(entry);
+        }
+        return;
+      }
+      if (message.type === "complete") {
+        try {
+          assertJsonValue(message.value, "return");
+          finish({ value: message.value });
+        } catch (error) {
+          finish({ error: new Error(`Script return could not be persisted: ${error.message}`) });
+        }
+        return;
+      }
+      if (message.type === "error") return finish({ error: new Error(typeof message.error === "string" ? message.error : "Script strategy failed.") });
+      if (message.type !== "call" || typeof message.callId !== "number" || message.method !== "run" || !isRecord(message.args)) return;
+      let key;
+      try {
+        key = validateKey(message.args.key);
+      } catch (error) {
+        return respond(message.callId, Promise.reject(error));
+      }
+      const params = message.args.params;
+      if (!isRecord(params)) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}', params) requires a params object.`)));
+      const tool = params.tool ?? params.cmd;
+      if (typeof tool !== "string" || !tool) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}') requires a tool string.`)));
+      const args = params.args === undefined ? {} : params.args;
+      if (!isRecord(args)) return respond(message.callId, Promise.reject(new Error(`tools.run('${key}') args must be an object.`)));
+      const collectFailure = message.args.collectFailure === true;
+      const startedAt = Date.now();
+      trace.push({ key, tool, state: "started" });
+      onEvent({ type: "script.tool.started", key, tool, startedAt: new Date().toISOString() });
+      respond(message.callId, Promise.resolve().then(async () => {
+        try {
+          const output = await executeTool(tool, args, { signal: childController.signal });
+          const result = { key, tool, ok: true, output };
+          trace.push({ key, tool, state: "completed", durationMs: Date.now() - startedAt });
+          onEvent({ type: "script.tool.completed", key, tool, endedAt: new Date().toISOString() });
+          return result;
+        } catch (error) {
+          const text = error instanceof Error ? error.message : String(error);
+          const result = { key, tool, ok: false, error: text };
+          trace.push({ key, tool, state: "failed", durationMs: Date.now() - startedAt, error: text });
+          onEvent({ type: "script.tool.failed", key, tool, error: text, endedAt: new Date().toISOString() });
+          if (!collectFailure) throw new Error(`Tool '${key}' failed: ${text}`);
+          return result;
+        }
+      }));
+    });
+
+    worker.postMessage({ type: "start", script, input });
+  });
+}
+
+module.exports = { runWorkflowScript };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",
@@ -10,7 +10,8 @@
     "agent",
     "cli",
     "cdp",
-    "devtools"
+    "devtools",
+    "pi-package"
   ],
   "author": "Nico Bailon",
   "license": "MIT",
@@ -28,6 +29,7 @@
   },
   "files": [
     "native/",
+    "pi-extension/",
     "playbooks/",
     "scripts/",
     "dist/",
@@ -38,7 +40,7 @@
   "scripts": {
     "dev": "vite build --watch --mode development",
     "build": "vite build",
-    "check": "tsc --noEmit",
+    "check": "tsc --noEmit && tsc --noEmit -p tsconfig.pi-extension.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "lint:test": "biome check test/",
@@ -64,11 +66,24 @@
   "devDependencies": {
     "@biomejs/biome": "^2.5.4",
     "@types/chrome": "^0.2.2",
+    "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "^4.1.9",
     "@vitest/ui": "^4.1.9",
-    "puppeteer": "25.3.0",
+    "puppeteer": "25.4.0",
     "typescript": "^7.0.2",
     "vite": "^8.1.4",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "typebox": "^1.3.11"
+  },
+  "pi": {
+    "extensions": [
+      "./pi-extension/surf.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "typebox": "*"
   }
 }