From 3fe054464f8a9d54e1d8875135d2d483c1cae2b0 Mon Sep 17 00:00:00 2001 From: rgarcia <72655+rgarcia@users.noreply.github.com> Date: Sat, 15 Aug 2026 20:39:54 +0000 Subject: [PATCH] Position the docs around the neutral core, not pi --- README.md | 34 +++++++++++++++++++++------------- docs/architecture.md | 4 +++- package.json | 2 +- packages/loop/README.md | 14 ++++++++++---- packages/loop/package.json | 2 +- 5 files changed, 36 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index a705890..393aba9 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,13 @@ # loop -Browser tools for your agent, built on [pi](https://github.com/earendil-works/pi). +Browser tools for your agent. The agent can be a [pi](https://github.com/earendil-works/pi) +`Agent` or `AgentHarness` — or your coding harness through a plugin — with Eve and +AI SDK bindings anticipated next. Kernel Loop supplies the tools, the +[Kernel cloud browser](https://kernel.sh/) they run against, and the per-model +compatibility knowledge. -Point any model at a [Kernel cloud browser](https://kernel.sh/): pick the tools, -get plain agent objects back, and run whatever loop you already have. +Point any model at a Kernel browser: pick the tools, get plain agent objects +back, and run whatever loop you already have. ```ts import { loop } from "@onkernel/loop"; @@ -16,8 +20,10 @@ const { model, agentTools, models } = kb.compile({ }); ``` -Already in pi? Install the extension instead and keep pi's session, UI, and -model selection: +The extension is the other half of the workflow: a harness is where you find +out which tools and which model actually work for a use case, and the SDK is +what you deploy into your production agent. Same catalog, same tool identities, +same model knowledge on both sides, so the hand-off is lossless: ```bash pi install npm:@onkernel/loop @@ -44,7 +50,9 @@ This repo does all of that and stops there. `@onkernel/loop` represents the provider differences as an explicit, identity-keyed tool catalog; you choose the exact tools, and provider transforms compose only the declarations and request fields those identities require. It does not supply an agent class, a session -format, or a front-end — your framework already has those. +format, or a front-end — your framework already has those. Tool identities +(`kloop.*.v1`) and model-facing names are byte-identical across bindings, so +transcripts and evals stay comparable wherever the same catalog runs. --- @@ -52,14 +60,14 @@ format, or a front-end — your framework already has those. ``` packages/ -├── loop/ # @onkernel/loop - tools, catalog compilation, pi bindings, pi extension +├── loop/ # @onkernel/loop - framework-neutral core, pi binding, pi extension └── ptywright/ # @onkernel/ptywright - development-only PTY/TUI test infrastructure ``` | Entry point | What it ships | | --- | --- | -| `@onkernel/loop` | Canonical actions, tool factories/toolsets, catalog compilation, the tool menu, and Kernel-browser execution. | -| `@onkernel/loop/pi` | `attach()`: binds a Kernel browser and compiles a (model, tools) pair into plain pi objects, plus model resolution and provider adapters. | +| `@onkernel/loop` | The framework-neutral core: canonical actions, tool factories/toolsets, catalog compilation, the tool menu, and Kernel-browser execution. Imports nothing from pi — a unit test enforces the boundary. | +| `@onkernel/loop/pi` | The pi binding — the first of the framework bindings (`./eve` and `./ai-sdk` are the anticipated next). `attach()` binds a Kernel browser and compiles a (model, tools) pair into plain pi objects, plus model resolution and provider adapters. | | `pi.extensions` | A pi extension contributing those tools to pi's own agent session. | | [`@onkernel/ptywright`](packages/ptywright) | Development-only PTY/TUI test infrastructure. | @@ -143,12 +151,12 @@ per-tool verdict. ## How it works -1. **Model layer** — `@onkernel/loop/pi` opens pi-ai's whole model catalog and - composes provider declarations, headers, and payload transforms around it. - Catalog compilation is declaration-only: it never sees an executor. -2. **Execution layer** — `@onkernel/loop` materializes the caller's exact +1. **Execution layer** — `@onkernel/loop` materializes the caller's exact catalog over one shared resource pool and executes canonical actions through Kernel's computer API or a raw-CDP browser executor. +2. **Model layer** — `@onkernel/loop/pi` opens pi-ai's whole model catalog and + composes provider declarations, headers, and payload transforms around that + core. Catalog compilation is declaration-only: it never sees an executor. 3. **Transport** — the compiled catalog derives `model.api` from the selected tools, so a provider-native surface reaches the wire with the transport, headers, and payload shape it requires. diff --git a/docs/architecture.md b/docs/architecture.md index b2d3f05..5815d43 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -35,7 +35,9 @@ both explicitly and may use pi's orchestration primitives directly. `modelSupportsDeferredTools` interprets pi compat flags, and the published `loop` namespace composes `loop.providers.anthropic.supports` over core's declarations), transport derivation, the provider adapters, provider retry, - and header composition. + and header composition. `./pi` is the first binding; `./eve` and `./ai-sdk` + are the anticipated next, sharing the same identities and tool names so + transcripts stay comparable across frameworks. - `src/pi-extension/` contributes these tools to a pi session that pi itself owns. It is the one consumer that uses neither `attach()` nor the harness: pi owns the model collection and the agent loop, so the extension takes the two diff --git a/package.json b/package.json index 7cdb1e7..ac86e26 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "cua", "version": "0.1.0", - "description": "Kernel-cloud-browser computer-use: tools, catalog compilation, and pi bindings", + "description": "Browser tools for your agent: framework-neutral tool catalog, per-model compilation, Kernel-browser execution, and a pi binding", "type": "module", "private": true, "workspaces": [ diff --git a/packages/loop/README.md b/packages/loop/README.md index 7758482..75f79e9 100644 --- a/packages/loop/README.md +++ b/packages/loop/README.md @@ -1,10 +1,11 @@ # `@onkernel/loop` -Kernel browser computer-use for pi: tool declarations, per-model catalog -compilation, Kernel-browser execution, the `attach()` binding for -`@earendil-works/pi-agent-core`, and a pi extension. +Browser tools for your agent: a framework-neutral core (tool declarations, +per-model catalog compilation, Kernel-browser execution) plus a pi binding +(`attach()` for `@earendil-works/pi-agent-core`) and a pi extension. -Two entry points: +One package, two entry points: the neutral core and the pi binding — the first +binding; Eve and AI SDK are anticipated next. | import | what it is | | --- | --- | @@ -466,6 +467,11 @@ browser they run against, and the provider wiring provider-native surfaces need. It does not start a second model loop, and it adds no implicit screenshots or prompt instructions. +The extension is not a lesser version of the SDK; it is the other half of the +workflow. Experiment in the harness to find which tools and model fit a use +case, then deploy the same catalog — same identities, same names — through +`attach()` in your production agent. + ```sh pi install npm:@onkernel/loop diff --git a/packages/loop/package.json b/packages/loop/package.json index b9efb95..08f548a 100644 --- a/packages/loop/package.json +++ b/packages/loop/package.json @@ -1,7 +1,7 @@ { "name": "@onkernel/loop", "version": "0.11.0", - "description": "Kernel browser computer-use tools, catalog compilation, and pi bindings", + "description": "Browser tools for your agent: framework-neutral tool catalog, per-model compilation, Kernel-browser execution, and a pi binding + extension", "license": "MIT", "type": "module", "main": "./dist/index.js",