Fix cua-ai ESM packaging, error-handling docs, API consistency

.agents/skills/release/SKILL.md

@@ -130,7 +130,7 @@ Run the checks for each package being released:
 ```bash
 npm ci
 npm run build --workspace @onkernel/cua-ai
-npm test --workspace @onkernel/cua-ai -- test/api-keys.test.ts test/models.test.ts test/providers.test.ts test/runtime-spec.test.ts test/tools.test.ts test/yutori-payload.test.ts
+npm test --workspace @onkernel/cua-ai
 npm pack --workspace @onkernel/cua-ai --dry-run
 ```
 
@@ -139,10 +139,15 @@ For `@onkernel/cua-agent`:
 ```bash
 npm run build --workspace @onkernel/cua-ai
 npm run build --workspace @onkernel/cua-agent
-npm test --workspace @onkernel/cua-agent -- test/agent.test.ts test/tool-exhaustiveness.test.ts
+npm test --workspace @onkernel/cua-agent
 npm pack --workspace @onkernel/cua-agent --dry-run
 ```
 
+Run the full unit suites — do not pass individual test files. `cua-ai`
+excludes integration/live tests by default (`npm run test:integration
+--workspace @onkernel/cua-ai` runs them separately), and the `cua-agent` live
+e2e tests skip unless `CUA_E2E_LIVE=1` is set.
+
 Do not push release tags if build, tests, or pack dry-runs fail.
 
 ## Commit To Main
@@ -201,6 +206,19 @@ npm view @onkernel/cua-agent@<version> version
 npm dist-tag ls @onkernel/cua-agent
 ```
 
+Then verify the published artifact actually imports — `npm view` only proves
+the version exists, not that the tarball is loadable:
+
+```bash
+cd "$(mktemp -d)"
+npm init -y
+npm install @onkernel/cua-ai@<version>
+node --input-type=module -e "import('@onkernel/cua-ai').then((m) => { if (typeof m.getCuaModel !== 'function') process.exit(1); })"
+```
+
+For `@onkernel/cua-agent`, install `@onkernel/cua-agent@<version>` the same
+way and check `typeof m.CuaAgent === "function"`.
+
 If a workflow fails after a tag is pushed, do not reuse the same package
 version unless npm did not publish it. Fix forward with a new commit and a new
 patch version when a package version has reached npm.

.github/workflows/ci.yml

@@ -17,12 +17,21 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
       - run: npm ci
       - run: npm run build --workspace @onkernel/cua-ai
       - name: Unit tests
-        run: npm test --workspace @onkernel/cua-ai -- test/models.test.ts test/tools.test.ts
+        run: npm test --workspace @onkernel/cua-ai
+      - name: Pack tarball
+        run: npm pack --workspace @onkernel/cua-ai --pack-destination "$RUNNER_TEMP"
+      - name: ESM import smoke test
+        run: |
+          mkdir -p "$RUNNER_TEMP/esm-smoke"
+          cd "$RUNNER_TEMP/esm-smoke"
+          npm init -y
+          npm install "$RUNNER_TEMP"/onkernel-cua-ai-*.tgz
+          node --input-type=module -e "import('@onkernel/cua-ai').then((m) => { if (typeof m.getCuaModel !== 'function') process.exit(1); })"
 
   integration:
     runs-on: ubuntu-latest
@@ -34,7 +43,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
       - run: npm ci
       - run: npm run build --workspace @onkernel/cua-ai
@@ -45,7 +54,7 @@ jobs:
           GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
           TZAFON_API_KEY: ${{ secrets.TZAFON_API_KEY }}
           YUTORI_API_KEY: ${{ secrets.YUTORI_API_KEY }}
-        run: npm test --workspace @onkernel/cua-ai -- test/computer-tool.integration.test.ts
+        run: npm run test:integration --workspace @onkernel/cua-ai
 
   agent-e2e:
     runs-on: ubuntu-latest
@@ -57,7 +66,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           cache: npm
       - run: npm ci
       - run: npm run build --workspace @onkernel/cua-ai

.github/workflows/release-cua-ai.yml

@@ -60,17 +60,18 @@ jobs:
       - run: npm run build --workspace @onkernel/cua-ai
 
       - name: Unit tests
-        run: >
-          npm test --workspace @onkernel/cua-ai --
-          test/api-keys.test.ts
-          test/models.test.ts
-          test/providers.test.ts
-          test/runtime-spec.test.ts
-          test/tools.test.ts
-          test/yutori-payload.test.ts
-
-      - name: Pack dry run
-        run: npm pack --workspace @onkernel/cua-ai --dry-run
+        run: npm test --workspace @onkernel/cua-ai
+
+      - name: Pack tarball
+        run: npm pack --workspace @onkernel/cua-ai --pack-destination "$RUNNER_TEMP"
+
+      - name: ESM import smoke test
+        run: |
+          mkdir -p "$RUNNER_TEMP/esm-smoke"
+          cd "$RUNNER_TEMP/esm-smoke"
+          npm init -y
+          npm install "$RUNNER_TEMP"/onkernel-cua-ai-*.tgz
+          node --input-type=module -e "import('@onkernel/cua-ai').then((m) => { if (typeof m.getCuaModel !== 'function') process.exit(1); })"
 
       - name: Publish to npm
         run: npm publish --workspace @onkernel/cua-ai --access public

.gitignore

@@ -7,6 +7,7 @@ dist/
 .DS_Store
 *.tsbuildinfo
 packages/*/dist/
+packages/*/dist-tsc/
 packages/*/*.tsbuildinfo
 packages/*/native/build/
 packages/ptywright/.cache/

README.md

@@ -42,14 +42,26 @@ All of them expect you to:
 
 ```
 packages/
-├── cua-translator/   # @onkernel/cua-translator   - shared SDK types + translator + browser-session
-├── cua-openai/       # @onkernel/cua-openai       - gpt-* (batch_computer_actions + computer_use_extra)
-├── cua-anthropic/    # @onkernel/cua-anthropic    - claude-* (computer_20251124 + batch_computer_actions + onPayload)
-├── cua-gemini/       # @onkernel/cua-gemini       - gemini-* (predefined functions + batch_computer_actions)
-├── cua-yutori/       # @onkernel/cua-yutori       - n1* (Navigator browser actions)
-└── cua-cli/          # @onkernel/cua-cli          - the CLI; depends on all providers above
+├── ai/               # @onkernel/cua-ai           - CUA model catalog + tool schemas + provider adapters (on npm)
+├── agent/            # @onkernel/cua-agent        - CuaAgent/CuaAgentHarness Kernel-browser execution loop (on npm)
+├── cua-translator/   # @onkernel/cua-translator   - [deprecated] shared SDK types + translator + browser-session
+├── cua-openai/       # @onkernel/cua-openai       - [deprecated] gpt-* (batch_computer_actions + computer_use_extra)
+├── cua-anthropic/    # @onkernel/cua-anthropic    - [deprecated] claude-* (computer_20251124 + batch_computer_actions + onPayload)
+├── cua-gemini/       # @onkernel/cua-gemini       - [deprecated] gemini-* (predefined functions + batch_computer_actions)
+├── cua-yutori/       # @onkernel/cua-yutori       - [deprecated] n1* (Navigator browser actions)
+└── cua-cli/          # @onkernel/cua-cli          - the CLI; depends on the cua-* providers above
 ```
 
+**Building your own agent? Start here:** [`packages/agent`](packages/agent)
+(`@onkernel/cua-agent`) — `CuaAgent`/`CuaAgentHarness` run the full
+computer-use loop against a Kernel browser. It sits on
+[`packages/ai`](packages/ai) (`@onkernel/cua-ai`), the model layer with the
+curated computer-use model catalog, canonical tool schemas, and per-provider
+adapters on top of pi-ai; reach for cua-ai directly only when you bring your
+own execution. Both are published to npm. The `cua-*` packages below are
+deprecated — cua-ai/cua-agent are the canonical source now — and remain only
+to back the `cua` CLI.
+
 ```mermaid
 flowchart LR
   trans[("@onkernel/cua-translator")]
@@ -74,11 +86,13 @@ flowchart LR
 
 | Package                                               | What it ships                                                                                                                            |
 | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| [`@onkernel/cua-translator`](packages/cua-translator) | Provider-agnostic `ComputerTranslator`, key/scroll/drag math, `goto`/`back`/`forward`/`url` builders, browser-session helper.            |
-| [`@onkernel/cua-openai`](packages/cua-openai)         | `batch_computer_actions` + `computer_use_extra` AgentTools and JSON Schemas for OpenAI computer-use models.                              |
-| [`@onkernel/cua-anthropic`](packages/cua-anthropic)   | `computer` (built-in `computer_20251124`) + `batch_computer_actions` AgentTools, beta-header stream wrapper, payload hook.               |
-| [`@onkernel/cua-gemini`](packages/cua-gemini)         | 13 per-action AgentTools matching Gemini's predefined computer-use functions, plus `batch_computer_actions`. Coordinate denormalization. |
-| [`@onkernel/cua-yutori`](packages/cua-yutori)         | AgentTools matching Yutori Navigator browser actions, with outbound payload filtering so Yutori uses its built-in action set.             |
+| [`@onkernel/cua-ai`](packages/ai)                     | Computer-use model catalog (`getCuaModel`/`listCuaModels`), canonical CUA tool schemas, and provider adapters/runtime specs built on pi-ai. On npm. |
+| [`@onkernel/cua-agent`](packages/agent)               | `CuaAgent`/`CuaAgentHarness` classes that execute cua-ai tool calls against a Kernel browser, screenshot loop included. On npm.          |
+| [`@onkernel/cua-translator`](packages/cua-translator) | **Deprecated** (use `cua-ai`/`cua-agent`). Provider-agnostic `ComputerTranslator`, key/scroll/drag math, `goto`/`back`/`forward`/`url` builders, browser-session helper.            |
+| [`@onkernel/cua-openai`](packages/cua-openai)         | **Deprecated** (use `cua-ai`/`cua-agent`). `batch_computer_actions` + `computer_use_extra` AgentTools and JSON Schemas for OpenAI computer-use models.                              |
+| [`@onkernel/cua-anthropic`](packages/cua-anthropic)   | **Deprecated** (use `cua-ai`/`cua-agent`). `computer` (built-in `computer_20251124`) + `batch_computer_actions` AgentTools, beta-header stream wrapper, payload hook.               |
+| [`@onkernel/cua-gemini`](packages/cua-gemini)         | **Deprecated** (use `cua-ai`/`cua-agent`). 13 per-action AgentTools matching Gemini's predefined computer-use functions, plus `batch_computer_actions`. Coordinate denormalization. |
+| [`@onkernel/cua-yutori`](packages/cua-yutori)         | **Deprecated** (use `cua-ai`/`cua-agent`). AgentTools matching Yutori Navigator browser actions, with outbound payload filtering so Yutori uses its built-in action set.             |
 | [`@onkernel/cua-cli`](packages/cua-cli)               | The `cua` binary: argv parsing, config, sessions, skills, JSONL output, pi-tui front-end.                                                |
 
 ---
@@ -364,6 +378,8 @@ bin/
 skills/
 └── cua-cli/SKILL.md            # skill aimed at OTHER agents driving cua via shell
 packages/
+├── ai/                         # @onkernel/cua-ai — model layer (see packages/ai/README.md)
+├── agent/                      # @onkernel/cua-agent — Kernel-browser execution layer (see packages/agent/README.md)
 ├── cua-translator/
 │   └── src/
 │       ├── types.ts            # ModelAction / BatchAction / errors
@@ -420,8 +436,9 @@ packages/
 
 ## Roadmap
 
-- Publish each `@onkernel/cua-*` package to npm so `kernel/cli`
-  templates and other consumers can depend on them directly.
+- Publish the remaining per-provider `@onkernel/cua-*` packages to npm
+  (`@onkernel/cua-ai` and `@onkernel/cua-agent` are already published) so
+  `kernel/cli` templates and other consumers can depend on them directly.
 - Auto-respawn dead Kernel sessions when `-s <name>` is used (today we
   refuse with a clear error and ask the user to re-`session start`).
 - `--local` Docker-backed browser as an alternative to Kernel cloud.