Multiplayer agent harness for work.
browse/kernel: use the shared Kernel credential through the broker (#2384)
Joshua France5e5f15749d81
diff --git a/skills-seed/browse/SKILL.md b/skills-seed/browse/SKILL.mdindex a720c553f..0f19800e8 100644--- a/skills-seed/browse/SKILL.md+++ b/skills-seed/browse/SKILL.md@@ -21,13 +21,16 @@ Which provider you use is decided by which API key is available in your env (orthrough the keychain). Org keys arrive automatically: an admin saves a provider's key as anorg credential delivered as sandbox env (admin UI → Service credentials → delivery "Sandboxenv"), and it rides into every all-internal conversation — nothing here is deploy config. A-person's own keychain key overrides the org one. Keys you may see today:+person's own keychain key overrides the org one. A provider can also be offered as a shared+credential you call through QM's broker without ever holding the key; the provider doc+says so when it supports that (Kernel does, via `service_kernel`). Keys you may see today:Use the absolute directory reported by the skill read for all `providers/` paths below.Keep the same explicit `sandbox_id` for the skill read and every `execute` commandin this flow, including the runner.-- `KERNEL_API_KEY` → **Kernel** (onkernel.com). Read `providers/kernel.md`.+- `KERNEL_API_KEY`, or a `service_kernel` shared credential in your inventory →+ **Kernel** (onkernel.com). Read `providers/kernel.md`.- `ANCHOR_API_KEY` → **Anchor** (anchorbrowser.io). Read `providers/anchor.md`.- `BROWSERBASE_API_KEY` → **Browserbase** (browserbase.com). Read`providers/browserbase.md`.@@ -45,15 +48,12 @@ in this flow, including the runner.Read the provider doc BEFORE creating anything — it owns every provider-shaped step:creating and deleting the browser, the person's profile, routing a sign-in wall, and givingthe browser a file. Its create step sets `CDP_URL` and `LIVE_VIEW`, which is all the shared-runner below needs. This file owns everything else: when to browse at all, the DM-only rule,+runner below needs. This file owns everything else: when to browse at all,key logistics, the runner, spending, and reporting. Where this file says "your provider key"or "your profile env key", substitute the names the provider doc gives.-**Sign-ins and profiles are DM-only.** The person's browser profile and any sign-in /-live-view links are bearer material: a keychain grant minted in a channel becomes usable by-the whole room, and a login link posted there can be clicked by anyone first. In a channel-or group, browse only profile-less — skip the profile entirely, launch the browser with no-profile, and decline tasks that need an account.+**Always browse with the person's profile from their keychain.** If they don't have one+yet, create one and store it in their keychain (first-time setup below).## Prerequisites (each run)@@ -99,8 +99,8 @@ of them (asks and drops are refused only on trigger-fired turns).```bashcurl -fsS "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGENT_API_TOKEN"```-2. **Registered to the person themselves** → in their DM, its handle is already usable in- `credentials`. Anywhere else, send an ask (step 3); they approve it on the card.+2. **Registered to the person themselves** → if its handle is in your manifest, use it in+ `credentials`. Otherwise send an ask (step 3); they approve it on the card.3. **Registered to someone else** (the provider key usually lives with whoever set it up) →send an ask: `POST /v1/keychain/asks` with the credential id and the person's words asthe purpose. Core DMs the owner and wakes this conversation when they answer; tell the@@ -122,7 +122,7 @@ curl -fsS "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGEN```- **Credential exists** → use that handle in `credentials`. Never bootstrap in this case.-- **No credential at all** → first-time setup below, with the person's OK.+- **No credential at all** → first-time setup below.**First-time profile setup (only when the check above found no credential).** Mint theprofile value — a random name, unless the provider doc's Profiles section says the@@ -143,8 +143,8 @@ curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capabilit## 1. Create the browser-Follow your provider doc's "Create the browser" section. In a DM, launch it with the-person's profile; in a channel or group, launch profile-less (per the DM-only rule). The+Follow your provider doc's "Create the browser" section. Launch it with the+person's profile. Thestep leaves you with `CDP_URL` (the websocket the runner drives) and `LIVE_VIEW` (thehuman-viewable session URL). Treat `CDP_URL` as a secret — some providers embed the API keyin it; it rides only as a runner argument, never into chat or logs.@@ -267,7 +267,7 @@ The last stdout line is the typed outcome:browser itself, on delete or stop; Browserbase and Anchor save only from a dedicatedsign-in session — the provider doc says which its flow uses.) Two rules hold for allproviders: sign-in and live-view links are single-audience- bearer material — hand them to the person in a DM, never open them yourself; and a+ bearer material — hand them only to the person, never open them yourself; and amid-session verification check (already signed in, then challenged) is cleared on the LIVEbrowser — hand the person `$LIVE_VIEW`, wait for done, re-run.diff --git a/skills-seed/browse/providers/anchor.md b/skills-seed/browse/providers/anchor.mdindex b52cac85f..617e2ec81 100644--- a/skills-seed/browse/providers/anchor.md+++ b/skills-seed/browse/providers/anchor.md@@ -31,7 +31,7 @@ the person asks to reset their state).## Create the browser-In a DM, with the person's profile:+With the person's profile:```bashCREATE=$(curl -fsS -X POST https://api.anchorbrowser.io/v1/sessions \@@ -42,16 +42,6 @@ ANCHOR_SID=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.loadLIVE_VIEW=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin)['data'].get('live_view_url',''))")```-In a channel or group, OMIT the profile entirely (per the DM-only rule):--```bash-CREATE=$(curl -fsS -X POST https://api.anchorbrowser.io/v1/sessions \- -H "anchor-api-key: $ANCHOR_API_KEY" -H 'content-type: application/json' \- -d '{"session":{"timeout":{"max_duration":30,"idle_timeout":10}}}')-```--then extract `CDP_URL` / `ANCHOR_SID` / `LIVE_VIEW` from `$CREATE` exactly as above.-Timeouts are minutes (`max_duration` caps the session, `idle_timeout` reaps an unused one).For a site behind serious bot protection, add a proxy and Anchor's hardened build — bothare billed extras, so reach for them on a block, not by default:@@ -115,7 +105,7 @@ Hand over the returned `url` with the consent stated plainly: _filling it storeswith Anchor (our managed-browser provider) so it can sign in and re-sign-in for you_ — thatstorage is the point, and it needs their explicit OK. Redemption fires a wake back intothis conversation; name the new credential's handle in `credentials` to get-`EMAIL`/`PASSWORD` for that command (sign-ins are DM-only, so no grant dance). Then create the identity with Python building the body from env+`EMAIL`/`PASSWORD` for that command. Then create the identity with Python building the body from env(`POST /v1/identities` with `{"source":"https://<domain>","name":...,"credentials":[{"type":"username_password","username":...,"password":...}]}`), and register the returnedidentity id in their keychain (service `anchor-identity`, envKeydiff --git a/skills-seed/browse/providers/browser-use.md b/skills-seed/browse/providers/browser-use.mdindex 71023fb73..8d52baad0 100644--- a/skills-seed/browse/providers/browser-use.md+++ b/skills-seed/browse/providers/browser-use.md@@ -48,7 +48,7 @@ sites the profile holds state for.## Create the browser-In a DM, with the person's profile. First make sure no browser is still running on the+With the person's profile. First make sure no browser is still running on theperson's profile — state is written only when a browser stops, so one left running holdsit. The v4 list doesn't say which profile a session is on, so every browser this doccreates is tagged with its profile id in `metadata`, and the check stops only tagged@@ -90,16 +90,6 @@ LIVE_VIEW=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(the websocket the runner drives. Both it and `LIVE_VIEW` are bearer material — anyoneholding either controls the browser.-In a channel or group, OMIT `profileId` (per the DM-only rule):--```bash-CREATE=$(curl -fsS -X POST https://api.browser-use.com/api/v4/browsers \- -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" -H 'content-type: application/json' \- -d '{"timeout":30}')-```--then extract `BU_SID` / `CDP_URL` / `LIVE_VIEW` exactly as above.-`timeout` is minutes (1–240). `proxyCountryCode` defaults to `"us"`; pass another ISOcode to change it, or `null` to drop the proxy. Browsers bill per minute, refundedpro rata on stop.diff --git a/skills-seed/browse/providers/browserbase.md b/skills-seed/browse/providers/browserbase.mdindex 63686af8e..c4b4807b8 100644--- a/skills-seed/browse/providers/browserbase.md+++ b/skills-seed/browse/providers/browserbase.md@@ -44,7 +44,7 @@ again through the same live-view flow below.`keepAlive` matters everywhere here: without it the session dies as soon as a CDP clientdisconnects, so a runner retry or the sign-in handoff below would find a dead browser.-(It needs the Hobby plan or above.) In a DM, with the person's context:+(It needs the Hobby plan or above.) With the person's context:```bashCREATE=$(curl -fsS -X POST https://api.browserbase.com/v1/sessions \@@ -62,16 +62,6 @@ goes stale once the task opens more tabs. Whenever you hand a live-view link overe-fetch `/v1/sessions/$BB_SID/debug` at hand-off time and pick the right entry from`pages[]` (each has its own `debuggerFullscreenUrl`, `url`, and `title`).-In a channel or group, OMIT `browserSettings.context` entirely (per the DM-only rule):--```bash-CREATE=$(curl -fsS -X POST https://api.browserbase.com/v1/sessions \- -H "X-BB-API-Key: $BROWSERBASE_API_KEY" -H 'content-type: application/json' \- -d '{"keepAlive":true,"timeout":1800}')-```--then extract `CDP_URL` / `BB_SID` / `LIVE_VIEW` exactly as above.-Timeout is seconds (60–21600); captcha solving is on by default. For a site behindserious bot protection, add top-level `"proxies":true` and`"browserSettings":{"advancedStealth":true}` (a Scale-plan feature) — billed extras,diff --git a/skills-seed/browse/providers/kernel.md b/skills-seed/browse/providers/kernel.mdindex e51bcc00a..8b8ffc1a5 100644--- a/skills-seed/browse/providers/kernel.md+++ b/skills-seed/browse/providers/kernel.md@@ -7,25 +7,82 @@ Provider names for the shared flow in SKILL.md: API key `KERNEL_API_KEY`, keychaexport PROFILE_ENV=KERNEL_PROFILE PROFILE_SERVICE=kernel-profile```-In a DM, name three handles in `credentials`: the Kernel key (if it isn't org env), the+Name three handles in `credentials`: the Kernel key (see "Which key" below), theperson's `KERNEL_PROFILE`, and their `KERNEL_PROXY_ID` (see "The person's static IP").+## Which key++Use the first of these that exists:++1. **The person's own key**: a `KERNEL_API_KEY` handle of theirs in your keychain+ manifest. Name it in `credentials`.+2. **An org key delivered as env**: `KERNEL_API_KEY` already set in your shell.+3. **The org's shared Kernel credential**: a `service_kernel` row in the Credentials+ inventory (proxy, host `api.onkernel.com`). Name `service_kernel` in `credentials`.+ You never see this key. QM adds it to each request you send through its credential+ broker (see the use-shared-credential skill), so `KERNEL_API_KEY` stays unset.++Make every Kernel API call in this doc through `kapi METHOD PATH [JSON-BODY]`, which+picks the right route, prints the response body, and on any error exits non-zero with+the status and body on stderr. Define it once per shell:++```bash+kapi() {+ if [ -n "${KERNEL_API_KEY:-}" ]; then+ if [ -n "${3:-}" ]; then+ curl -fsS -X "$1" "https://api.onkernel.com$2" -H "Authorization: Bearer $KERNEL_API_KEY" \+ -H 'content-type: application/json' -d "$3"+ else+ curl -fsS -X "$1" "https://api.onkernel.com$2" -H "Authorization: Bearer $KERNEL_API_KEY"+ fi+ else+ python3 - "$1" "$2" "${3:-}" <<'PY'+import json, os, sys, urllib.error, urllib.request+method, path, body = sys.argv[1:4]+req = {"credential": "kernel", "method": method, "url": "https://api.onkernel.com" + path}+if body:+ req["headers"] = {"content-type": "application/json"}+ req["body"] = body+r = urllib.request.Request(os.environ["AGENT_API_URL"] + "/v1/credentials/broker",+ data=json.dumps(req).encode(), method="POST",+ headers={"x-agent-capability": os.environ["AGENT_CREDENTIAL_TOKEN"], "content-type": "application/json"})+try:+ env = json.load(urllib.request.urlopen(r))+except urllib.error.HTTPError as e:+ sys.stderr.write(f"broker {e.code}: {e.read().decode()[:500]}\n"); sys.exit(1)+if not 200 <= env.get("status", 0) < 300:+ sys.stderr.write(f"kernel {env.get('status')}: {(env.get('body') or '')[:500]}\n"); sys.exit(1)+sys.stdout.write(env.get("body") or "")+PY+ fi+}+```++The shared credential only creates and deletes (see "Org setup"), so with it you can't+list or read anything back, and can't upload files (the broker carries JSON, not+multipart). The flow below needs neither.+## Org setup (admins: required before rollout)This doc's isolation depends on two settings that the skill can't enforce itself:-1. **Shared credential: create and delete only.** Configure the org's shared Kernel- credential (the broker entry for `api.onkernel.com`) with methods `POST` and `DELETE`- only, on paths `/browsers` and `/profiles`. Do NOT allow `GET`: the paths match by- prefix, so any `GET` lets callers list every person's profiles and running browsers,+1. **Shared credential: its own project, create and delete only.** Give QM's shared key+ a dedicated Kernel project and a key restricted to it (`browsers`, `profiles` and+ `proxies`, each with `use`, `create`, `write` and `delete` on `projects/<id>/*`, and no+ `read`). Kernel requires project-wide `browsers:use` to create a browser at all, and+ that also lets the key list and attach to every running browser in its project, so+ never put the shared key in a project that people's own keys or other tools use. Then+ configure the broker entry for `api.onkernel.com` with methods `POST` and `DELETE` only,+ on paths `/browsers`, `/profiles` and `/proxies`. Do NOT allow `GET`: the paths match+ by prefix, so any `GET` lets callers list every person's profiles and running browsers,and their names are all anyone needs to open someone else's signed-in browser.Nothing in this flow needs `GET`; the live view and CDP URL come back from the create.2. **Personal keys scoped to the person.** A person's own `KERNEL_API_KEY` must not be an- account-wide key on the shared Kernel account; it would bypass rule 1. Give them their- own Kernel project (or a key restricted to their project), so the only profiles it can- see are theirs.+ account-wide key; it would bypass rule 1. Give them their own Kernel project and a key+ restricted to it, for the same reason as above: within one project, any key that can+ create browsers can see every running browser.-If you're an agent and the shared credential's listing shows `GET`, tell the person+If you're an agent and the `service_kernel` row in your inventory allows `GET`, tell the person(and an org admin) that profiles aren't isolated yet. Don't work around it.## Profiles@@ -49,9 +106,7 @@ first-time setup, and whenever the create below 400s, create the profile under tname from the keychain — never a fresh random one, which would orphan the credential:```bash-curl -fsS -X POST https://api.onkernel.com/profiles \- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \- -d "{\"name\":\"$KERNEL_PROFILE\"}" > /dev/null+kapi POST /profiles "{\"name\":\"$KERNEL_PROFILE\"}" > /dev/null```## The person's static IP@@ -61,16 +116,14 @@ the same on every session. Sites that remember devices (LinkedIn especially) seeperson on one connection instead of a new address every run, which is what keeps asaved sign-in from tripping verification. Its id lives in their keychain as`KERNEL_PROXY_ID` (service `kernel-proxy`); treat it like the profile name (it decides-whose address the browser wears), so it comes only from the keychain, in a DM.+whose address the browser wears), so it comes only from the keychain.If the manifest has no `KERNEL_PROXY_ID` handle, run the same existence check SKILL.mdgives for the profile (`envKey == "KERNEL_PROXY_ID"`). Only when none exists, create onewith the person's OK (it is a paid, per-person resource) and register it:```bash-PX=$(curl -fsS -X POST https://api.onkernel.com/proxies \- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \- -d '{"type":"isp","name":"qm-<person>-isp","config":{"country":"US"}}' \+PX=$(kapi POST /proxies '{"type":"isp","name":"qm-<person>-isp","config":{"country":"US"}}' \| python3 -c "import sys,json;print(json.load(sys.stdin)['id'])")[ -n "$PX" ] || { echo "proxy create returned no id; nothing registered" >&2; exit 1; }curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capability: $AGENT_API_TOKEN" \@@ -78,17 +131,18 @@ curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" -H "x-agent-capabilit-d "{\"service\":\"kernel-proxy\",\"envKey\":\"KERNEL_PROXY_ID\",\"secret\":\"$PX\"}" > /dev/null```-ISP proxies exist in US, GB, FR, DE and SG; pick the person's country. Use the person's-own `KERNEL_API_KEY` for this when they have one (a shared brokered Kernel credential-may only allow `/browsers` and `/profiles`). The first session from the new IP may ask the+ISP proxies exist in US, GB, FR, DE and SG; pick the person's country. If the shared+credential refuses `/proxies` (path_not_allowed), the org hasn't enabled it; launch+without a proxy and tell the person. The first session from the new IP may ask theperson to verify once on sites they were already signed in to elsewhere; after that it isstable. If a create fails on the proxy (`proxy_id` not found), check it with-`POST /proxies/$KERNEL_PROXY_ID/check` and tell the person rather than silently launching-without it.+`kapi POST /proxies/$KERNEL_PROXY_ID/check` (own or env key only; the shared credential+has no read access, so the check is refused) and tell the person rather than silently+launching without it.## Create the browser-In a DM, with the person's profile and proxy. Only ONE browser may write to a profile at a+With the person's profile and proxy. Only ONE browser may write to a profile at atime: Kernel allows concurrent browsers on a profile, and each save replaces the wholeprofile, so a second writer silently clobbers the first. Since browsers can't be listed,record your own writer in the person's keychain (`KERNEL_ACTIVE`, service@@ -99,9 +153,7 @@ no writer):```bashSAVE=truecase "${KERNEL_ACTIVE:-}" in *:*) [ $(( $(date +%s) - ${KERNEL_ACTIVE#*:} )) -lt 1800 ] && SAVE=false;; esac-CREATE=$(curl -fsS -X POST https://api.onkernel.com/browsers \- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \- -d "{\"stealth\":true,\"headless\":false,\"timeout_seconds\":1800,\"proxy_id\":\"$KERNEL_PROXY_ID\",\"profile\":{\"name\":\"$KERNEL_PROFILE\",\"save_changes\":$SAVE}}")+CREATE=$(kapi POST /browsers "{\"stealth\":true,\"headless\":false,\"timeout_seconds\":1800,\"proxy_id\":\"$KERNEL_PROXY_ID\",\"profile\":{\"name\":\"$KERNEL_PROFILE\",\"save_changes\":$SAVE}}")CDP_URL=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin).get('cdp_ws_url',''))")KERNEL_SID=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin).get('session_id',''))")LIVE_VIEW=$(printf '%s' "$CREATE" | python3 -c "import sys,json;print(json.load(sys.stdin).get('browser_live_view_url',''))")@@ -120,20 +172,10 @@ when you report: anything this run signs in to won't be kept. The record is nottwo runs starting in the same moment can both see none — so keep one browse run at atime on a person's profile.-In a channel or group, OMIT the profile AND `proxy_id` entirely (per the DM-only rule) —-never send a personal profile name or proxy there:--```bash-CREATE=$(curl -fsS -X POST https://api.onkernel.com/browsers \- -H "Authorization: Bearer $KERNEL_API_KEY" -H 'content-type: application/json' \- -d '{"stealth":true,"headless":false,"timeout_seconds":1800}')-```--then extract `CDP_URL` / `KERNEL_SID` / `LIVE_VIEW` from `$CREATE` exactly as above.-## Giving the browser a file-Files land in `/home/kernel`:+Files land in `/home/kernel`. This needs a real key (own or env); the shared credential+can't carry a file upload, so say so rather than improvising:```bashcurl -fsS -X POST "https://api.onkernel.com/browsers/$KERNEL_SID/fs/upload" \@@ -148,7 +190,7 @@ Then run the task with `BROWSE_FILES="/home/kernel/receipt.jpg"` per SKILL.md.The person signs in once on the live browser; the profile keeps it.1. Navigate the live browser to the wall URL (read from `/tmp/wall-url.txt`, never shell- source) so the person lands on the login page, then hand them `$LIVE_VIEW` in the DM —+ source) so the person lands on the login page, then hand them `$LIVE_VIEW` —bearer material, never open it yourself. SKILL.md's shared `browse-nav.py` (written inits wall step) does the steering:@@ -171,7 +213,7 @@ password never leaves them.## Clean up```bash-curl -fsS -X DELETE "https://api.onkernel.com/browsers/$KERNEL_SID" -H "Authorization: Bearer $KERNEL_API_KEY"+kapi DELETE "/browsers/$KERNEL_SID"# release the profile if this run held it[ "$SAVE" = true ] && curl -fsS -X POST "$AGENT_API_URL/v1/keychain/credentials" \-H "x-agent-capability: $AGENT_API_TOKEN" -H 'content-type: application/json' \