@onkernel/cua-ai 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.3.1 - 2026-06-23
+
+- Add the `playwright_execute` tool definition: `CuaPlaywrightSchema`,
+  `CUA_PLAYWRIGHT_TOOL_NAME`, `CUA_PLAYWRIGHT_TOOL_DESCRIPTION`,
+  `createCuaPlaywrightToolDefinition()`, and the `CuaPlaywrightInput` type.
+
 ## 0.3.0 - 2026-06-12
 
 - Add `CuaSimpleStreamOptions`: pi-ai `SimpleStreamOptions` plus the

package/README.md

@@ -309,12 +309,15 @@ definitions and executors; it is forwarded to the provider module's
 - `createCuaNavigationToolDefinition()`, `CuaNavigationSchema`,
   `CUA_NAVIGATION_TOOL_NAME` (`"computer_use_extra"`),
   `CUA_NAVIGATION_TOOL_DESCRIPTION`
+- `createCuaPlaywrightToolDefinition()`, `CuaPlaywrightSchema`,
+  `CUA_PLAYWRIGHT_TOOL_NAME` (`"playwright_execute"`),
+  `CUA_PLAYWRIGHT_TOOL_DESCRIPTION`
 - `canonicalToolCallName(action)`, `canonicalToolCallArguments(action)` — map
   a normalized `CuaAction` back to its tool-call name/arguments
 - `normalizeGotoUrl(value)` — prefix bare hostnames with `https://`
 - Types: `CuaAction` (plus the 16 per-action interfaces), `CuaActionType`,
   `CuaMouseButton`, `CuaDragMouseButton`, `CuaBatchInput`,
-  `CuaNavigationInput`, `CuaToolExecutorSpec`, `ComputerToolsOptions`,
+  `CuaNavigationInput`, `CuaPlaywrightInput`, `CuaToolExecutorSpec`, `ComputerToolsOptions`,
   `ComputerToolCoordinateSystem`
 
 ### Provider registration

package/dist/index.d.ts

@@ -191,10 +191,15 @@ declare const CuaNavigationSchema: Type.TObject<{
   action: Type.TUnion<[Type.TLiteral<"goto">, Type.TLiteral<"back">, Type.TLiteral<"forward">, Type.TLiteral<"url">]>;
   url: Type.TOptional<Type.TString>;
 }>;
+declare const CuaPlaywrightSchema: Type.TObject<{
+  code: Type.TString;
+  timeout_sec: Type.TOptional<Type.TNumber>;
+}>;
 interface CuaBatchInput {
   actions: CuaAction[];
 }
 type CuaNavigationInput = Static<typeof CuaNavigationSchema>;
+type CuaPlaywrightInput = Static<typeof CuaPlaywrightSchema>;
 /** Tool schema plus execution adapter for a browser computer-use tool. */
 interface CuaToolExecutorSpec {
   /** Tool schema installed by CuaAgent/CuaAgentHarness. The name must match the provider tool call name. */
@@ -209,8 +214,10 @@ interface CuaToolExecutorSpec {
  */
 declare const CUA_BATCH_TOOL_NAME = "computer_batch";
 declare const CUA_NAVIGATION_TOOL_NAME = "computer_use_extra";
+declare const CUA_PLAYWRIGHT_TOOL_NAME = "playwright_execute";
 declare const CUA_BATCH_TOOL_DESCRIPTION: string;
 declare const CUA_NAVIGATION_TOOL_DESCRIPTION = "High-level browser navigation helpers for goto, back, forward, and url.";
+declare const CUA_PLAYWRIGHT_TOOL_DESCRIPTION: string;
 interface ComputerToolsOptions {
   actions?: readonly CuaActionType[];
 }
@@ -248,6 +255,7 @@ declare function createCuaBatchToolExecutor(actions?: readonly CuaActionType[],
 /** Build the provider's default CUA tool execution adapters. */
 declare function computerToolExecutors(options?: ComputerToolsOptions): CuaToolExecutorSpec[];
 declare function createCuaNavigationToolDefinition(): Tool;
+declare function createCuaPlaywrightToolDefinition(): Tool;
 interface CuaScreenshotTransformSpec {
   width: number;
   height: number;
@@ -582,4 +590,4 @@ declare const providerModule: {
   };
 };
 //#endregion
-export { CUA_ACTION_TYPES, CUA_BATCH_TOOL_DESCRIPTION, CUA_BATCH_TOOL_NAME, CUA_MODEL_ANNOTATIONS, CUA_NAVIGATION_TOOL_DESCRIPTION, CUA_NAVIGATION_TOOL_NAME, CUA_PROVIDERS, ComputerToolCoordinateSystem, ComputerToolsOptions, CuaAction, CuaActionBack, CuaActionClick, CuaActionCursorPosition, CuaActionDoubleClick, CuaActionDrag, CuaActionForward, CuaActionGoto, CuaActionKeypress, CuaActionMouseDown, CuaActionMouseUp, CuaActionMove, CuaActionSchema, CuaActionScreenshot, CuaActionScroll, CuaActionType, CuaActionTypeText, CuaActionUrl, CuaActionWait, CuaBatchInput, CuaBatchSchema, CuaDragMouseButton, CuaModelAnnotation, CuaModelInfo, CuaModelMatch, CuaModelRef, CuaMouseButton, CuaNavigationInput, CuaNavigationSchema, CuaPayloadContext, CuaPayloadHook, CuaProvider, CuaProviderModule, CuaRuntimeSpec, CuaRuntimeSpecInput, CuaScreenshotSpec, CuaScreenshotTransformSpec, CuaSimpleStreamOptions, CuaToolExecutorSpec, index_d_exports as anthropic, canonicalToolCallArguments, canonicalToolCallName, computerToolExecutors, computerTools, createCuaActionSchema, createCuaActionToolDefinitions, createCuaActionToolExecutors, createCuaBatchSchema, createCuaBatchToolDefinition, createCuaBatchToolExecutor, createCuaNavigationToolDefinition, cuaApiKeyEnvVarsForProvider, findCuaAnnotation, formatCuaModelRef, index_d_exports$1 as gemini, getCuaEnvApiKey, getCuaEnvApiKeyForModel, getCuaModel, isCuaProvider, listCuaModels, normalizeGotoUrl, index_d_exports$2 as openai, parseCuaModelRef, providerForModel, registerCuaProviders, requireCuaEnvApiKey, requireCuaEnvApiKeyForModel, resolveCuaRuntimeSpec, index_d_exports$3 as tzafon, index_d_exports$4 as yutori };
+export { CUA_ACTION_TYPES, CUA_BATCH_TOOL_DESCRIPTION, CUA_BATCH_TOOL_NAME, CUA_MODEL_ANNOTATIONS, CUA_NAVIGATION_TOOL_DESCRIPTION, CUA_NAVIGATION_TOOL_NAME, CUA_PLAYWRIGHT_TOOL_DESCRIPTION, CUA_PLAYWRIGHT_TOOL_NAME, CUA_PROVIDERS, ComputerToolCoordinateSystem, ComputerToolsOptions, CuaAction, CuaActionBack, CuaActionClick, CuaActionCursorPosition, CuaActionDoubleClick, CuaActionDrag, CuaActionForward, CuaActionGoto, CuaActionKeypress, CuaActionMouseDown, CuaActionMouseUp, CuaActionMove, CuaActionSchema, CuaActionScreenshot, CuaActionScroll, CuaActionType, CuaActionTypeText, CuaActionUrl, CuaActionWait, CuaBatchInput, CuaBatchSchema, CuaDragMouseButton, CuaModelAnnotation, CuaModelInfo, CuaModelMatch, CuaModelRef, CuaMouseButton, CuaNavigationInput, CuaNavigationSchema, CuaPayloadContext, CuaPayloadHook, CuaPlaywrightInput, CuaPlaywrightSchema, CuaProvider, CuaProviderModule, CuaRuntimeSpec, CuaRuntimeSpecInput, CuaScreenshotSpec, CuaScreenshotTransformSpec, CuaSimpleStreamOptions, CuaToolExecutorSpec, index_d_exports as anthropic, canonicalToolCallArguments, canonicalToolCallName, computerToolExecutors, computerTools, createCuaActionSchema, createCuaActionToolDefinitions, createCuaActionToolExecutors, createCuaBatchSchema, createCuaBatchToolDefinition, createCuaBatchToolExecutor, createCuaNavigationToolDefinition, createCuaPlaywrightToolDefinition, cuaApiKeyEnvVarsForProvider, findCuaAnnotation, formatCuaModelRef, index_d_exports$1 as gemini, getCuaEnvApiKey, getCuaEnvApiKeyForModel, getCuaModel, isCuaProvider, listCuaModels, normalizeGotoUrl, index_d_exports$2 as openai, parseCuaModelRef, providerForModel, registerCuaProviders, requireCuaEnvApiKey, requireCuaEnvApiKeyForModel, resolveCuaRuntimeSpec, index_d_exports$3 as tzafon, index_d_exports$4 as yutori };

package/dist/index.js

@@ -126,6 +126,10 @@ const CuaNavigationSchema = Type.Object({
 	]),
 	url: Type.Optional(Type.String())
 }, { additionalProperties: false });
+const CuaPlaywrightSchema = Type.Object({
+	code: Type.String({ description: "Playwright/TypeScript to run against the live browser. `page`, `context`, and `browser` are in scope; end with a `return` to send a JSON-serializable value back. Example: \"await page.goto('https://example.com'); return await page.title();\"" }),
+	timeout_sec: Type.Optional(Type.Number({ description: "Optional execution timeout in seconds. Default 60, max 300." }))
+}, { additionalProperties: false });
 /**
 * Default name for batch computer-action tools created by
 * {@link createCuaBatchToolDefinition} and the name Anthropic's batch tool
@@ -133,12 +137,19 @@ const CuaNavigationSchema = Type.Object({
 */
 const CUA_BATCH_TOOL_NAME = "computer_batch";
 const CUA_NAVIGATION_TOOL_NAME = "computer_use_extra";
+const CUA_PLAYWRIGHT_TOOL_NAME = "playwright_execute";
 const CUA_BATCH_TOOL_DESCRIPTION = [
 	"Execute multiple computer actions in sequence, including ordered read steps like url(), cursor_position(), and screenshot().",
 	"Prefer this tool for predictable browser interaction sequences such as click-then-type, typing a URL, keyboard navigation, drag paths, and mixed write/read batches.",
 	"If no explicit read step is included, the tool returns one fresh screenshot after execution."
 ].join("\n");
 const CUA_NAVIGATION_TOOL_DESCRIPTION = "High-level browser navigation helpers for goto, back, forward, and url.";
+const CUA_PLAYWRIGHT_TOOL_DESCRIPTION = [
+	"Run Playwright/TypeScript directly against the live browser session for steps that are awkward as raw pointer/keyboard actions: precise DOM reads, form fills, data extraction, and waiting on selectors.",
+	"`page`, `context`, and `browser` are in scope and the code may `return` a JSON-serializable value, which comes back as the result.",
+	"Each call runs in a fresh JS context — local variables do not persist across calls, but the browser session does (navigation, cookies, DOM state carry over via `page`/`context`/`browser`).",
+	"No screenshot is returned automatically; request one with a follow-up screenshot action when you need to see the page, rather than calling page.screenshot() inside the code."
+].join("\n");
 /**
 * Build the provider's CUA computer-use tools.
 *
@@ -211,6 +222,13 @@ function createCuaNavigationToolDefinition() {
 		parameters: CuaNavigationSchema
 	};
 }
+function createCuaPlaywrightToolDefinition() {
+	return {
+		name: CUA_PLAYWRIGHT_TOOL_NAME,
+		description: CUA_PLAYWRIGHT_TOOL_DESCRIPTION,
+		parameters: CuaPlaywrightSchema
+	};
+}
 //#endregion
 //#region src/providers/tzafon/provider.ts
 const TZAFON_RESPONSES_API = "tzafon-responses";
@@ -2028,4 +2046,4 @@ function resolveCuaRuntimeSpec(input, options) {
 //#region src/index.ts
 registerCuaProviders();
 //#endregion
-export { CUA_ACTION_TYPES, CUA_BATCH_TOOL_DESCRIPTION, CUA_BATCH_TOOL_NAME, CUA_MODEL_ANNOTATIONS, CUA_NAVIGATION_TOOL_DESCRIPTION, CUA_NAVIGATION_TOOL_NAME, CUA_PROVIDERS, CuaActionSchema, CuaBatchSchema, CuaNavigationSchema, anthropic_exports as anthropic, canonicalToolCallArguments, canonicalToolCallName, computerToolExecutors, computerTools, createCuaActionSchema, createCuaActionToolDefinitions, createCuaActionToolExecutors, createCuaBatchSchema, createCuaBatchToolDefinition, createCuaBatchToolExecutor, createCuaNavigationToolDefinition, cuaApiKeyEnvVarsForProvider, findCuaAnnotation, formatCuaModelRef, gemini_exports as gemini, getCuaEnvApiKey, getCuaEnvApiKeyForModel, getCuaModel, isCuaProvider, listCuaModels, normalizeGotoUrl, openai_exports as openai, parseCuaModelRef, providerForModel, registerCuaProviders, requireCuaEnvApiKey, requireCuaEnvApiKeyForModel, resolveCuaRuntimeSpec, tzafon_exports as tzafon, yutori_exports as yutori };
+export { CUA_ACTION_TYPES, CUA_BATCH_TOOL_DESCRIPTION, CUA_BATCH_TOOL_NAME, CUA_MODEL_ANNOTATIONS, CUA_NAVIGATION_TOOL_DESCRIPTION, CUA_NAVIGATION_TOOL_NAME, CUA_PLAYWRIGHT_TOOL_DESCRIPTION, CUA_PLAYWRIGHT_TOOL_NAME, CUA_PROVIDERS, CuaActionSchema, CuaBatchSchema, CuaNavigationSchema, CuaPlaywrightSchema, anthropic_exports as anthropic, canonicalToolCallArguments, canonicalToolCallName, computerToolExecutors, computerTools, createCuaActionSchema, createCuaActionToolDefinitions, createCuaActionToolExecutors, createCuaBatchSchema, createCuaBatchToolDefinition, createCuaBatchToolExecutor, createCuaNavigationToolDefinition, createCuaPlaywrightToolDefinition, cuaApiKeyEnvVarsForProvider, findCuaAnnotation, formatCuaModelRef, gemini_exports as gemini, getCuaEnvApiKey, getCuaEnvApiKeyForModel, getCuaModel, isCuaProvider, listCuaModels, normalizeGotoUrl, openai_exports as openai, parseCuaModelRef, providerForModel, registerCuaProviders, requireCuaEnvApiKey, requireCuaEnvApiKeyForModel, resolveCuaRuntimeSpec, tzafon_exports as tzafon, yutori_exports as yutori };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onkernel/cua-ai",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Kernel-curated computer-use model access built on pi-ai",
   "license": "MIT",
   "type": "module",