@byokit/openclaw 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.12.0 (2026-10-13)
+
+- FIX: an unsealed API key that a failed `addKey` could not clear (the gateway refused the clear after a restart ran late) is now dropped at the kit's first ready after start, so it no longer stays in the member's `byokit-key-<member>` store until the next add. A key whose ready marker exists is never cleared, and a sweep the gateway interrupts runs again on the next ready.
+- FEAT: An OpenCode Go plan key now runs every Go model, including `muse-spark-1.3-contributor` over the Responses API, with no model setup in the app. On each start and after `addKey`/`addAccount`, the kit asks the Go provider's own catalog hook (new plugin method `byokit.catalog`) for the live models. It registers each one with its `api` in `models.providers['opencode-go'].models`, so `models()` lists it and runs resolve it. It keeps each pinned Go model the live list omits, writes only when the list changed, never drops a registered model, and leaves the provider alone when `KitOptions.config` sets that list. Each model gets the endpoint the pinned engine routes, `https://opencode.ai/zen/go/v1`, not the live catalog's `inference/go/v1`, which the pinned engine refuses with `missing x-opencode-session`.
+- CHANGE: `run({ auth: 'apiKey', model })` accepts any model of the saved key's provider, not only the model saved at activation. Another provider still ends `plan`, now with the message "Choose a model of the provider saved with this key."
+- FIX: `signedIn(member, provider)` is true after `addKey` for that provider: it also counts a ready key whose saved model is that provider's. `providers(member)` still lists only the member's own sign-ins, the ones a run without `auth: 'apiKey'` uses.
+- FIX: an OpenCode Go plan key now sets up and runs on the pinned engine. `addAccount(member, { authChoice: 'opencode-go' })` (and `signIn` for any key-entry choice) asks for `Plan key` and pastes it into typed `openclaw.setup.activate { kind: 'api-key' }` instead of the setup wizard, which refused it ("That provider setup is not available on this Gateway."); a key-entry failure shows only the kit's words, never the engine's text. The plan key is sealed on the member agent (`seal { planKey: true }`: subscription billing). With a spawned engine, when the activation changes config `auth`, `done` waits out the gateway restart that causes (within 60 s); past that the sign-in ends `why: 'failed'` ("the engine took too long to restart") and is cleaned up, so nothing half-set-up is kept; `addKey` does the same and returns `retry`. A run started on done uses the new sign-in. The kit now writes `agents.defaults.modelPolicy = {}` unless the app sets a policy, and drops a saved `allow: ['openai/*']`: left unset, the pin turned the kit's `models` map into that allowlist and every non-OpenAI model fell back to openai. Discovery follows the engine: a key-entry choice without `appGuidedSecret`, or a login choice without `appGuidedAuth`/`appGuidedDiscovery`, is `no_upstream_flow` and never ready (22 routes at 2026.8.1, 15 of them new here, among them `fal-api-key`, `vllm`, `sglang` and `custom-api-key`; the 15 new no-upstream-flow choices are `fal-api-key`, `vllm`, `sglang`, `custom-api-key`, `alibaba-model-studio-api-key`, `clawrouter-api-key`, `cloudflare-ai-gateway-api-key`, `comfy-cloud-api-key`, `copilot-proxy`, `longcat-api-key`, `microsoft-foundry-entra`, `microsoft-foundry-apikey`, `pixverse-api-key`, `runway-api-key` and `vydra-api-key`); the engine job checks every ready and absent choice against the real Gateway. The pinned engine already sends OpenCode Go's required `x-opencode-session` (stable per conversation) on the activation probe and every run (kits before 0.10.0 pinned an engine without it); the engine job asserts it. The README and spec say how an app registers a live-only Go model such as Muse (`config.models.providers['opencode-go']`, `api: 'openai-responses'`).
+- FIX: Key-agent creation waits for the published roster before activation. `addKey` now waits for catalog synchronization and prepares the full-catalog owner once before success; preparation failures clear the attempted key and return a secret-safe `retry`/`engine`. A chosen live-catalog model must be in the engine's registered list before the key is sealed, or the add returns `retry`/`model`. Ordinary runs do not gain a cold refresh.
+- FIX: `addKey` accepts a catalog `model` for the Go live-catalog route and saves it for key-lane runs; `models(member, { authChoice })` lists that route's live catalog once a key is saved (empty before, with no agent queried), including Go Muse. Only an available row from that key lane can be selected; ordinary-member discovery is never used.
+- `addKey` now returns a typed `{ status, reason? }` result instead of a string, so callers compare `result.status === 'ok'` (migrate `result === 'ok'`). `invalid` now only means the provider refused the key (`auth`), its billing refused it (`billing`), or the key was blank (`empty`); unsupported routes and unknown models are `not_included` with `model`; every other failure is `retry` with `network`, `inference`, `engine` or `busy`. A member that is not your own now throws `Choose your own member.`, as `ensureMember` does, instead of returning a result. `model` is accepted only for the Go live-catalog route: on any other route it returns `not_included`/`model` before activation, and `models(member, { authChoice })` lists nothing for them. Failures never contain keys, key fragments, headers or raw engine diagnostics.
+- FEAT: OpenClaw kit S7 `kit.addAccount` identity merge: a sign-in whose identity (`who`) matches another account of the same member and provider moves into that account and `done.id` names it, so signing in again as the same account refreshes its row instead of adding one, whatever email it now reports and whatever `again` names. `again` with another identity adds a row and leaves the named account billing as before. A sign-in with no identity never merges, even with the same email. When several older accounts share an identity, the earliest added one takes the sign-in. The identity never appears in `accounts()`, views, errors or logs.
+- FEAT: OpenClaw kit S11 session binding: every run first finds the account its session is bound to (an account agent's key, or the agent of the member's that holds `agent:<that agent>:<tail>`, found with `sessions.resolve { allowMissing: true }`, member agent first), so a later run on one app key stays on that account. A key bound to an account agent resolves `'auto'`, `'default'` and no account to it, and refuses another id (`code: 'bound'`, words `account.bound`); when that account bills per use, anything but its own id is refused (`code: 'paid'`, words `account.paid`); a key bound to the member agent chooses only among its own accounts. Refusals end `kind: 'other'` after the binding read and before any room, model or agent request (one account listing when the index is cold); an `auth: 'apiKey'` run continues only an API-billed conversation (other bindings refuse with `account.bound`), and a conversation holding no account names `another account`. New `kit.pick(member, sel, { sessionKey })` returns exactly what `run` would decide with that key, `considered` included. `run` accepts a member's account-agent key; `steer`/`abort` map a live run's app key to its engine key. With no account agents, runs ask nothing more.
+- FEAT: OpenClaw kit S12 `kit.move({ member, sessionKey }, to)`: a conversation moves to another account. Its whole transcript (user turns, tool calls and results) forks onto the target account's agent with `sessions.create { fork: true, parentSessionKey }`, never `chat.history` plus `chat.inject`, under both agents' exclusive locks; then the source session is deleted only if it is still the session read (`expectedSessionId`, `expectedSessionUpdatedAt`). It answers `{ ok: true, session: 'agent:<target>:<tail>' }`, and the next run on the app key continues there. `unsupported` when the conversation is found nowhere, `busy` while a run is live on it (the kit's own runs or the engine's `hasActiveRun`), `start_failed` when the target is not ready or the engine refuses the fork (the source untouched), `close_failed` with `live` = the new key when the source cannot be deleted (both kept). A move within one agent forks nothing and answers its own key. A session already under the target key refuses the move `start_failed` (`move.taken`), the source untouched. A run that waited for its agent's lock across a move binds again under the lock and ends `{ ok: false, kind: 'other' }` (`run.moved`) before any event, so it never runs on the deleted key; a member-path run on a bound key now holds the member agent's shared lock. New words `move.unsupported`, `move.busy`, `move.notReady`, `move.closeFailed`, `move.taken`, `run.moved`. The fake gateway keeps per-session transcripts and serves `sessions.list` (`hasActiveRun`), `sessions.create { fork }`, `sessions.delete` and `chat.history`.
+- FEAT: OpenClaw kit O14m attribution and link/device account frames: one member-attribution rule, the kit's `memberOf`, maps an indexed `<member>--<hex6>` account agent and its session keys to `<member>`, and approvals, the bridge and the link adapter all use it instead of one copy per file. Link `oc.events`/`oc.sessions` carry an account agent's rows and events under its member, link `oc.run` accepts `account`/`needs` and streams the account frame first, and the device client sends `account`/`needs` and refuses a misshapen session key on `oc.run` before any request. An unindexed account-shaped agent maps nowhere, so it stays unreachable through events, sessions, approvals, steer/abort and bridge attribution, and `addAccount` refuses key material outright (keys stay host-only).
+- FIX: a paired device can sign in to an offered plan key (OpenCode Go) over the link. `oc.signIn.start('opencode-go', via)` no longer refuses with `This device can't do that.`: `routeFor` serves the provider's offered plan-key route whichever `via` the device asks, the host's `kit.signIn` asks `{ prompt: 'Plan key' }`, and `oc.signIn.paste` carries the key only inside the sealed link frame to the host, which activates and keeps it. No view, state or run frame sent back holds the key; a refused key shows only the kit's words.
+
 ## 0.11.1 (2026-10-12)
 
 - Dependency update: pins @byokit/discover 0.8.1.

package/README.md

@@ -22,7 +22,7 @@ npm install @byokit/openclaw
 
 Node 22.18 or later. The kit brings the engine with it: the first `start()` installs the pinned `openclaw@2026.8.35`
 under your `stateDir` (a few minutes, needs the network once), and later starts run from there. For a whole app, a
-phone page that pairs, signs in with ChatGPT, runs and answers approvals, see
+phone page that pairs, signs in to a plan (ChatGPT or a plan key), runs and answers approvals, see
 [`examples/openclaw-kit`](../../examples/openclaw-kit).
 
 ## Bundled engine provenance
@@ -135,10 +135,27 @@ once at run start), `'default'` (the saved default) or an id from `kit.accounts(
 for other models the run may call. The first event is `{ type: 'account', account, model, sessionKey, how, why, considered }`,
 and an ok end carries `account` and `model`. A chosen account that isn't signed in ends `signed-out` with no agent request;
 when every account is resting, the end is `resting` with `until`, and Auto skips a resting account until then.
+A conversation keeps its account: a later run on the same `sessionKey` stays on the account that holds the session,
+whatever `account` says. Naming another account ends `{ ok: false, kind: 'other' }` with words to show (`account.bound`).
+A conversation on an API-key account continues only when that account is named (`account.paid`). Both end after the
+binding read and before any room, model or agent request (a refusal reads the account listing once when the index is
+cold); an `auth: 'apiKey'` run first reads its key (`byokit.keys ready`), continues only an API-billed conversation and
+is refused other bindings the same way (`account.bound`). `kit.pick(member, { account, model?, needs? }, { sessionKey })`
+returns what that run would choose now, refusals included, without running. `steer` and `abort` accept the same
+`sessionKey` while its run is live.
 
 
 For an owner who explicitly offers keys, `kit.addKey('ana', { authChoice: 'openai-api-key', apiKey })` returns
-`ok`, `invalid` or `not_included`. Label the option **API key (billed per use)**. Select only `routes()` rows with
+`{ status: 'ok' }` or `{ status: 'invalid' | 'not_included' | 'retry', reason }`.
+`reason` is `auth` (provider refused the key) or `billing` (the provider's billing refused it; the kit words it and never passes
+provider text): both are `invalid`, and an unchanged key must not be retried. `empty` is a blank key, rejected locally before any
+provider call, also `invalid`. `model` is an unsupported route or unknown model (`not_included`), or a live model the engine did not
+register (`retry`). `network` is a timeout or transport failure; `inference` is a provider reply in an unexpected format, an unknown
+probe failure, or a typed request-validation refusal; `engine` is a control or preparation failure; `busy` is a rate limit or a
+restarting engine. `not_included` covers an unsupported route, an unknown chosen model and a probe reporting the route unavailable;
+every other failure is `retry`. Migrate from the old string result with `result.status === 'ok'`, not `result === 'ok'`.
+A member that is not your own throws. `retry` means the engine may have taken the key but it was not kept
+sealed (for example a gateway restart ran late); no usable key was kept, so add it again. Failures never contain keys, key fragments, headers or raw engine diagnostics. Label the option **API key (billed per use)**. Select only `routes()` rows with
 `keyEntry: true`; API rows remain `offer: false`. Each route also carries its engine `revision`, `checked` date,
 label and key error word names. Submit the input directly, clear the field afterwards, and never log or save it in
 app state. The kit never returns engine key-check errors or the key. [`@byokit/ui/kits`](../ui/README.md) supplies `keyStep`/`keyView`
@@ -146,12 +163,25 @@ for entry, checking, success and failure states, using the kit's `key.*` words.
 
 To use the saved key for one run, pass `auth: 'apiKey'`. The key lives in the member's separate
 `byokit-key-<member>` agent and workspace, with `copyToAgents: false` and only that key in its local auth order.
-Its selected model is used; omit `model` or pass that same model. Key runs have separate history. To steer or stop
+List the route's models with `kit.models('ana', { authChoice: 'opencode-go' })` after a key is saved; this reads the
+live catalog. Before a key exists it returns `[]` and queries no agent. Only available key-lane
+models can be saved; the ordinary member's sign-ins never supply the list. Pass a full catalog id, e.g.
+`model: 'opencode-go/muse-spark-1.3-contributor'`, to `addKey` to save it as the lane's default after activation.
+Model listing and selection are Go-only: other key routes list no models, and a `model` on them returns `not_included`/`model`
+before activation.
+An unknown model returns `{ status: 'not_included', reason: 'model' }` and clears the replacement.
+Before success, `addKey` waits for catalog registration and prepares the new key agent's full-catalog owner once.
+For a live-catalog provider, a chosen model must also be in the engine's registered `models.providers[provider].models`
+list before anything is sealed; otherwise the add clears the attempt and returns `{ status: 'retry', reason: 'model' }`.
+Preparation failure clears the attempted key and returns `{ status: 'retry', reason: 'engine' }`; ordinary runs stay unchanged.
+With no choice, today's starter stays.
+The saved model is used when a run's `model` is omitted; any other model of the same provider (`provider/model`) runs too,
+and another provider ends `plan`. Key runs have separate history. To steer or stop
 one, pass `{ auth: 'apiKey' }` to `steer` or `abort` too (the device helpers accept the same option).
 Ordinary runs never enter the key agent, even when the subscription is resting. This agent boundary is necessary
 because the engine's profile pins can rotate. The `byokit-key-` member prefix is reserved. Adding another key
 replaces the previous key; a failed replacement leaves this option unavailable. If the normal agent already has
-an API key added through pass-through calls, `addKey` returns `invalid` and leaves that key untouched.
+an API key added through pass-through calls, `addKey` returns `{ status: 'retry', reason: 'engine' }` and leaves that key untouched.
 
 `OpenClawKit.abort` always returns a Promise. Await it or attach `.catch(...)`: an unavailable engine, transport
 failure or invalid API-key session key rejects with the original error, never throws synchronously, and is not
@@ -166,7 +196,9 @@ without a new accepted frame emit no `started`. Handle these frames explicitly r
 non-text/tool frame as an end.
 Live readiness reads (`providers`, `signedIn`, or device `state()`) prepare admission for the next run, avoiding
 redundant checks while authority remains reusable. `providerStatus(member)` returns `undefined` for unknown
-status rather than `[]`; `providers` maps unknown to `[]`, and `signedIn` to `false`.
+status rather than `[]`; `providers` maps unknown to `[]`, and `signedIn` to `false`. `signedIn(member, provider)`
+is also true when the member holds a ready API key for that provider (`addKey`), while `providers` lists only the
+member's own sign-ins, the ones a run without `auth: 'apiKey'` uses; a key run passes `auth: 'apiKey'`.
 See [the admission contract](../../docs/runtime-kits.md#58-runs-members-and-streams) for lifetime, expiry,
 file witnesses, invalidation and remote-revocation limits.
 Tool events carry the engine's call `id`, the `input` on `start` and the `output` and `error` on `end`. A run that
@@ -334,7 +366,7 @@ streams, [`examples/openclaw-kit`](../../examples/openclaw-kit) for a whole app,
 
 Subscription sign-ins are offered by default. API-billed routes remain in `kit.routes()` with `offer: false`;
 apps can offer them when the app or person opts in, labelled API key (billed per use). Each `Route` carries `billing` (`subscription`, `api` or
-`local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. The pinned Gateway guides only some routes; other choices need manual paste or key entry. Pass the accounts the app offers in `KitOptions.offered` (the provider, auth choice or alias each route carries, e.g. `'openrouter'`); the kit allow-lists the plugin of every route those name, so an opted-in sign-in is not blocked. An app can still name a plugin directly in `config.plugins.allow`, and pass the route's `choice` explicitly to `kit.signIn()`.
+`local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. A plan key (OpenCode Go: `kit.addAccount(member, { authChoice: 'opencode-go' }, on)`) asks for `Plan key`; `paste` it and the engine live-tests it before `done`. A paired device starts the same sign-in with either `via` and pastes the key over the sealed link, which keeps it on the host. A run reaches the pinned engine's static Go models (default `opencode-go/deepseek-v4-pro`); the kit keeps OpenCode Go's `x-opencode-session` header on every request, the setup probe included. A live-only Go model such as Muse needs no app config: the kit registers the plan's live catalog with each model's API, so `run({ model: 'opencode-go/muse-spark-1.3-contributor' })` runs on the account (or with `auth: 'apiKey'` on a Go key); an app that sets `config.models.providers['opencode-go'].models` keeps its own list. A choice the pinned Gateway cannot set up has readiness `no_upstream_flow` and is never offered. Pass the accounts the app offers in `KitOptions.offered` (the provider, auth choice or alias each route carries, e.g. `'openrouter'`); the kit allow-lists the plugin of every route those name, so an opted-in sign-in is not blocked. An app can still name a plugin directly in `config.plugins.allow`, and pass the route's `choice` explicitly to `kit.signIn()`.
 Offered provider plugins are allowed by default alongside the app's plugin ids.
 
 ## API at a glance

package/SECURITY.md

@@ -147,8 +147,9 @@ asks expire, deny when the caller disconnects, and are removed on shutdown.
 Native exec/plugin decisions use `allow-once`, not a persistent allowlist.
 The engine remains authoritative for native approval expiration and resolution.
 
-`openclawLink` checks the app's member mapping and session prefix before member
-operations, checks pending approval ownership before deciding, and denies mutation
+`openclawLink` checks the app's member mapping and each session key's owner (`kit.memberOf`,
+which maps an indexed account agent's keys to its member) before member operations, checks
+pending approval ownership before deciding, and denies mutation
 to view grants. Raw `oc.call` is denied unless the app's `passThrough` explicitly
 allows the method; that callback must also enforce parameter/member scope. The
 local `kit.call`/`kit.decide` surface has operator authority and is trusted host

package/dist/accounts.d.ts

@@ -1,5 +1,11 @@
 import { createLocks } from './locks.ts';
-import type { Account, AccountId, AccountPick, Defaults, GatewayTransport, Member, ModelInfo, Room, RunSelection, SignInOptions, SignInView } from './types.ts';
+import type { Account, AccountId, AccountPick, Defaults, GatewayTransport, Member, ModelInfo, MoveResult, Room, RunSelection, SignInOptions, SignInView } from './types.ts';
+export declare const modelsOf: (provider: string, answer: unknown) => ModelInfo[];
+/** The agent a session lives on (5.15 Runs step 1); `id` absent: the member agent, which may hold several accounts. */
+export type Binding = {
+    agentId: string;
+    id?: AccountId;
+};
 type AddOptions = {
     authChoice: string;
     via?: 'browser' | 'code';
@@ -20,6 +26,7 @@ type StartSignIn = (agentId: string, o: SignInOptions, on: (v: SignInView) => vo
     cancel(): void;
     done: Promise<SignInView>;
 };
+export declare function memberOfAccount(root: string, ref: string): Member | undefined;
 export declare function createAccounts(ctx: {
     request: GatewayTransport['request'];
     root: string;
@@ -29,6 +36,9 @@ export declare function createAccounts(ctx: {
     }>;
     locks: ReturnType<typeof createLocks>;
     signIn: StartSignIn;
+    routes: ReadonlyMap<string, {
+        session: string;
+    }>;
     log?: (line: string) => void;
 }): {
     list(member: Member): Promise<Account[]>;
@@ -38,10 +48,13 @@ export declare function createAccounts(ctx: {
     setDefaults(member: Member, d: Defaults): Promise<void>;
     models(member: Member, id: AccountId): Promise<ModelInfo[]>;
     room(member: Member, id: AccountId, demand?: string[]): Promise<Room>;
-    pick(member: Member, sel: RunSelection, skip?: readonly AccountId[]): Promise<{
+    bind(member: Member, sessionKey: string): Promise<Binding | undefined>;
+    keyRefusal(member: Member, binding: Binding): Promise<string | undefined>;
+    pick(member: Member, sel: RunSelection, skip?: readonly AccountId[], binding?: Binding): Promise<{
         pick: AccountPick;
         agent?: string;
     }>;
     rest(member: Member, id: AccountId, until: number): Promise<void>;
+    move(member: Member, sessionKey: string, to: AccountId): Promise<MoveResult>;
 };
 export {};