Upgrade pi to 0.83.0 and adopt context-first harness tools

docs/agent-tool-configuration-spec.md

@@ -138,7 +138,6 @@ const agent = new CuaAgent({
 const harness = new CuaAgentHarness({
   browser,
   client,
-  env,
   session,
   model: "openai:gpt-5.6-sol",
   tools: [
@@ -603,7 +602,7 @@ Every provider tool surface must expose the first-party source it mirrors. CUA-a
 2. **Payload transforms:** transforms consume stable identities, declare static write claims, and compose in a fixed phase order.
 3. **Result ownership:** each tool returns only requested reads, explicit screenshots, or its own structured semantic feedback.
 4. **Batch overlap:** batches are mechanical; `browser_act` remains semantic; browser batches share ref state without a workflow DSL.
-5. **Dynamic loading:** `setTools()` uses pi 0.80.10 additive markers only for final, cache-preserving in-tool additions; other changes are eager.
+5. **Dynamic loading:** `setTools()` uses pi 0.83.0 additive markers only for final, cache-preserving in-tool additions; other changes are eager.
 6. **Shared resources:** one resource pool survives tool/model changes and owns the translator and lazy CDP executor.
 7. **Provider exports:** the native OpenAI, Anthropic, Google, Tzafon, and Yutori surfaces are namespaced, cite first-party sources, and are tested against their declared contracts. Meta, xAI, and Moonshot use CUA-authored browser tools; the CLI explicitly appends `browser_act` to the Meta and xAI catalogs. Moonshot is excluded: its API accepts the complex `browser_wait_for` schema but rejects a request carrying `browser_act`'s much larger one, so the catalog gates oversized schemas separately from merely-complex ones.
 

packages/agent/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 0.10.0 - 2026-08-04
+
+Breaking: upgrade `@earendil-works/pi-agent-core` and `@earendil-works/pi-ai`
+to 0.83.0 and adopt pi's context-first harness API.
+
+- `CuaAgentHarness` and `CuaAgentHarnessOptions` now take the tool context as
+  their first type parameter — `CuaAgentHarness<TContext, TSkill,
+  TPromptTemplate>` — mirroring pi's `AgentHarness` generic order. The
+  supplied `toolContext` is forwarded to pi untouched, and every executable
+  harness tool receives the exact object on each call.
+- Executable harness tools are pi `AgentHarnessTool`s via the new
+  `CuaHarnessTool<TContext>` union (a CUA spec or an `AgentHarnessTool`).
+  `CuaAgent` stays on the ordinary pi `AgentTool` (`CuaAgentTool`); the two
+  tool APIs are no longer conflated.
+- Remove `CuaAgentHarnessOptions.env` and `CuaAgentHarness.env`. Execution
+  environments now travel through the tool context (for example
+  `toolContext: { env: new NodeExecutionEnv({ cwd }) }` for pi's
+  read/bash/edit/write tools). No alias is preserved.
+- Remove `CuaSystemPromptCallback`; `systemPrompt` is pi's
+  `AgentHarnessSystemPrompt` through the harness options.
+- Keep `streamFn` optional on `CuaAgentOptions` (CUA supplies its default
+  stream) even though pi 0.83.0 makes `AgentOptions.streamFn` required.
+- Published declarations target pi's TypeBox 1.3 as-is; a downstream compile
+  test with `skipLibCheck: false` guards the packaged types.
+- Preserve explicit Tzafon screenshot results in model context even when they
+  fall outside `toolResultImageReplayLimit`, because its native continuation
+  protocol requires those images. Other tool-result images remain bounded.
+
 ## 0.9.0 - 2026-08-03
 
 - Add OpenRouter Kimi K3 support through `@onkernel/cua-ai` 0.9.0,

packages/agent/README.md

@@ -48,7 +48,6 @@ compaction, steering, and follow-ups:
 import {
   CuaAgentHarness,
   InMemorySessionRepo,
-  NodeExecutionEnv,
 } from "@onkernel/cua-agent";
 import { cua } from "@onkernel/cua-ai";
 
@@ -57,7 +56,6 @@ const session = await repo.create();
 const harness = new CuaAgentHarness({
   client,
   browser,
-  env: new NodeExecutionEnv({ cwd: process.cwd() }),
   session,
   model: "openai:gpt-5.6-sol",
   tools: cua.toolsets.browser(),
@@ -70,6 +68,37 @@ await harness.prompt("Find the pricing page.");
 The package re-exports pi-agent-core session, skill, prompt-template, compaction,
 and execution-environment primitives used with the harness.
 
+### Tool context
+
+Executable harness tools are pi `AgentHarnessTool`s: `execute` receives the
+harness's tool context as its last argument. Supply it once as `toolContext`
+and pi delivers the exact object (or the result of a zero-argument provider)
+to every tool call:
+
+```ts
+import {
+  CuaAgentHarness,
+  NodeExecutionEnv,
+  createBashTool,
+  createReadTool,
+  type ExecutionToolContext,
+} from "@onkernel/cua-agent";
+
+const harness = new CuaAgentHarness<ExecutionToolContext>({
+  client,
+  browser,
+  session,
+  model: "openai:gpt-5.6-sol",
+  tools: [createReadTool(), createBashTool(), ...cua.toolsets.browser()],
+  toolContext: { env: new NodeExecutionEnv({ cwd: process.cwd() }) },
+  systemPrompt: "Use the supplied tools.",
+});
+```
+
+CUA specs and plain pi `AgentTool`s are accepted too — they simply ignore the
+context. The low-level `CuaAgent` stays context-free: its tools are ordinary
+pi `AgentTool`s (`CuaAgentTool`).
+
 ## Choosing tools
 
 ```ts
@@ -173,7 +202,9 @@ Tools return only requested feedback:
   textual markers.
 
 `toolResultImageReplayLimit` controls how many recent tool-result images remain
-in model context (`4` by default, or `false` to disable projection).
+in model context (`4` by default, or `false` to disable projection). Tzafon
+native screenshot results are exempt because its continuation protocol requires
+the image.
 
 ## Custom tools
 

packages/agent/examples/harness-openai-smoke.ts

@@ -1,6 +1,6 @@
 import Kernel from "@onkernel/sdk";
 import { cua, requireCuaEnvApiKeyForModel, type CuaModelRef } from "@onkernel/cua-ai";
-import { CuaAgentHarness, InMemorySessionRepo, NodeExecutionEnv } from "../src/index";
+import { CuaAgentHarness, InMemorySessionRepo } from "../src/index";
 import { logAgentEvent, logAssistant } from "./shared/logging";
 import { SCENARIOS } from "./shared/scenarios";
 
@@ -19,7 +19,6 @@ async function main(): Promise<void> {
 		const harness = new CuaAgentHarness({
 			browser,
 			client,
-			env: new NodeExecutionEnv({ cwd: process.cwd() }),
 			model: modelRef,
 			session,
 			// Prefer structured browser refs and semantic reads for the OpenAI smoke,

packages/agent/examples/harness-provider-matrix.ts

@@ -3,7 +3,7 @@ import {
 	requireCuaEnvApiKeyForModel,
 	type CuaModelRef,
 } from "@onkernel/cua-ai";
-import { CuaAgentHarness, InMemorySessionRepo, NodeExecutionEnv } from "../src/index";
+import { CuaAgentHarness, InMemorySessionRepo } from "../src/index";
 import { logAgentEvent, logAssistant } from "./shared/logging";
 import { SCENARIOS } from "./shared/scenarios";
 import { toolsForModel } from "./shared/tools";
@@ -25,7 +25,6 @@ async function main(): Promise<void> {
 		const harness = new CuaAgentHarness({
 			browser,
 			client,
-			env: new NodeExecutionEnv({ cwd: process.cwd() }),
 			model: modelRef,
 			session,
 			tools: toolsForModel(modelRef),

packages/agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onkernel/cua-agent",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Kernel browser computer-use Agent and AgentHarness classes built on pi-agent-core",
   "license": "MIT",
   "type": "module",
@@ -43,9 +43,9 @@
     "typecheck": "tsc -b"
   },
   "dependencies": {
-    "@earendil-works/pi-agent-core": "0.80.10",
-    "@earendil-works/pi-ai": "0.80.10",
-    "@onkernel/cua-ai": "0.9.0",
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
+    "@onkernel/cua-ai": "0.10.0",
     "@onkernel/sdk": "0.49.0",
     "sharp": "^0.35.3"
   },