@byokit/openclaw 0.22.2 → 0.23.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.23.0 (2026-10-20)
+
+- FEATURE: A signed-out `claude-cli` run now says why: its end carries `cause: { code: 'needs_cli_login', cli: 'claude', home, configDir?, signIn }` (the new `CliLoginCause` type, also on `./device`). `signIn: true` means `kit.signIn(member, { authChoice: 'anthropic-cli' })` runs the Claude Code login into the kit's own folder (subscription billing); `signIn: false` means the engine reads the person's own Claude Code login, so they run `claude` on that machine. An `anthropic-cli` sign-in the kit cannot run carries the same `cause` on its failed view. `kind`, `message` and every other run end are unchanged.
+
 ## 0.22.2 (2026-10-19)
 
 - Dependency update: pins @byokit/accounts 0.28.2.

package/README.md

@@ -131,7 +131,9 @@ API key (billed per use) entry still requires explicit selection; there is no su
 To choose the model for a run, pass `model: 'provider/model'` in the run spec (for example
 `'openai/gpt-5.1'`, where `provider` is an id `kit.providers(member)` lists). That provider is the one called and billed for this run only, with no fallback to another
 provider or model. If the member isn't signed in to it, the run ends `{ ok: false, kind: 'signed-out' }` and the
-engine is never called. Leave `model` out to keep the engine's own choice. A specific sign-in (`@profile`) can't be
+engine is never called. A signed-out `claude-cli` run also carries `cause: { code: 'needs_cli_login', cli: 'claude', home, configDir?, signIn }`:
+with `signIn: true` offer `kit.signIn(member, { authChoice: 'anthropic-cli' })`, which runs the Claude Code login; with
+`signIn: false` ask the person to run `claude` on this machine to sign in. Leave `model` out to keep the engine's own choice. A specific sign-in (`@profile`) can't be
 picked per run: the pinned engine may still switch to another sign-in for the same provider.
 
 To let the kit choose among a member's accounts, pass `account: 'auto'` (the account with the most room left, decided

package/dist/device.d.ts

@@ -4,7 +4,7 @@ import type { RouteView } from './routes.ts';
 import { type AccountView } from './words.ts';
 import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, RunFrame, SignInView, AccountRef } from './types.ts';
 export type { GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult } from './types.ts';
-export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
+export type { Approval, CliLoginCause, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
 /** One `oc.events` frame: a member's Gateway event, typed by name, or an approval add/resolve (7.2). */
 export type OpenClawLinkEvent = {
     [E in GatewayEventName]: {

package/dist/engine.d.ts

@@ -1,7 +1,7 @@
 import { remoteCliHost } from '@byokit/accounts/cli';
 import { AuthStore, AuthStoreSealSizeError } from './auth-store.ts';
 import type { KitOptions } from './kit.ts';
-import type { KitState, ToolSpec } from './types.ts';
+import type { CliLoginCause, KitState, ToolSpec } from './types.ts';
 /** The app's stateDir as an absolute path with no symlinked ancestor (macOS /tmp and /var are symlinks):
  * the native Claude login's accounts store refuses any other, so a relative or symlinked stateDir failed it. */
 export declare function canonicalStateDir(dir: string): string;
@@ -83,9 +83,10 @@ export declare class Engine {
     refreshInstalledClaudeLogin(): Promise<boolean>;
     /** The fallback Claude sign-in for a machine whose installed Claude Code is signed out: it signs into the engine's folder. */
     nativeClaudeLogin(): ReturnType<typeof remoteCliHost>;
-    /** Whether a fallback sign-in would write a folder this engine's gateway does not read: it started on the person's
-     * login location (installed sign-in, or a probe with no answer), and an in-process restart keeps that env. */
-    claudeLoginUnread(): boolean;
+    /** Where a Claude Code login must be for this engine's gateway to read it. `signIn: false` when a fallback sign-in
+     * would write a folder the gateway does not read: it started on the person's login location (installed sign-in, or
+     * a probe with no answer), and an in-process restart keeps that env. */
+    claudeLoginCause(): CliLoginCause;
     resetNativeClaudeLogin(): Promise<void>;
     doctor(timeoutMs: number): {
         status: number | null;

package/dist/engine.js

@@ -528,9 +528,16 @@ export class Engine {
         this.claudeLogin = remoteCliHost({ cli, bins });
         return this.claudeLogin;
     }
-    /** Whether a fallback sign-in would write a folder this engine's gateway does not read: it started on the person's
-     * login location (installed sign-in, or a probe with no answer), and an in-process restart keeps that env. */
-    claudeLoginUnread() { return Boolean(this.o.spawnEngine) && !this.claudeFallback; }
+    /** Where a Claude Code login must be for this engine's gateway to read it. `signIn: false` when a fallback sign-in
+     * would write a folder the gateway does not read: it started on the person's login location (installed sign-in, or
+     * a probe with no answer), and an in-process restart keeps that env. */
+    claudeLoginCause() {
+        if (this.o.spawnEngine && !this.claudeFallback) {
+            const { HOME, CLAUDE_CONFIG_DIR } = personal();
+            return { code: 'needs_cli_login', cli: 'claude', home: HOME, ...CLAUDE_CONFIG_DIR ? { configDir: CLAUDE_CONFIG_DIR } : {}, signIn: false };
+        }
+        return { code: 'needs_cli_login', cli: 'claude', home: join(this.root, 'home'), configDir: this.claudeFolder, signIn: true };
+    }
     resetNativeClaudeLogin() {
         if (this.claudeReset)
             return this.claudeReset;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, ChannelChat, ChannelMessage, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunRef, Helper, DelegatedRun, DelegatedEvent, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, TelegramChannel, ToolHost, ToolSpec, } from './types.ts';
+export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, CliLoginCause, ChannelChat, ChannelMessage, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunRef, Helper, DelegatedRun, DelegatedEvent, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, TelegramChannel, ToolHost, ToolSpec, } from './types.ts';
 export type { GatewayMethods } from './generated/methods.ts';
 export type { JsonValue } from './output.ts';
 export type { RouteFacts, RouteView } from './routes.ts';

package/dist/kit.js

@@ -1120,7 +1120,7 @@ export class OpenClawKit {
             ensure: (member) => this.ensureMember(member), callbackPort: this.o.callbackPort ?? 1455,
             nativeClaudeLogin: () => this.engine.nativeClaudeLogin(),
             resetNativeClaudeLogin: () => this.engine.resetNativeClaudeLogin(),
-            claudeLoginUnread: () => this.engine.claudeLoginUnread(),
+            claudeLogin: () => this.engine.claudeLoginCause(),
             onDisconnect: (fn) => { this.signInDisconnects.add(fn); return () => { this.signInDisconnects.delete(fn); }; },
             stopSignal: this.engine.stopSignal,
             authConfig: () => this.authSnapshot(),
@@ -1387,6 +1387,7 @@ export class OpenClawKit {
             request: (method, params, o) => this.request()(method, params, o),
             authStatus: this.admission.read,
             invalidateAuth: this.admission.invalidate,
+            claudeLogin: () => this.engine.claudeLoginCause(),
             onEvent: (fn) => {
                 this.listeners.add(fn);
                 return () => {

package/dist/runs.d.ts

@@ -5,7 +5,7 @@ import type { createAccounts } from './accounts.ts';
 import type { createLocks } from './locks.ts';
 import { authStatus } from './auth-status.ts';
 import { outputSchema, type OutputSchema, type SchemaOutput } from './output.ts';
-import type { GatewayTransport, Member, RunEnd, RunEvent, RunFrame, RunSpec } from './types.ts';
+import type { CliLoginCause, GatewayTransport, Member, RunEnd, RunEvent, RunFrame, RunSpec } from './types.ts';
 export declare const USABLE: Set<string>;
 /**
  * The providers a `models.authStatus` answer shows usable (the rule a picked account is checked by), lowercased and
@@ -35,6 +35,7 @@ export declare function createRuns(ctx: {
     request: GatewayTransport['request'];
     authStatus?: (agentId: string, refresh: boolean, native: boolean) => ReturnType<typeof authStatus>;
     invalidateAuth?: () => void;
+    claudeLogin?: () => CliLoginCause;
     onEvent: GatewayTransport['onEvent'];
     ensure(member: Member): Promise<{
         agentId: string;

package/dist/runs.js

@@ -154,11 +154,14 @@ export function createRuns(ctx) {
             return undefined;
         }
     };
-    const failure = (message) => {
+    // A signed-out claude-cli run names where its Claude Code login is missing (`cause`).
+    const cause = (provider) => provider === 'claude-cli' && ctx.claudeLogin ? { cause: ctx.claudeLogin() } : {};
+    const signedOut = (provider, message) => ({ ok: false, kind: 'signed-out', message, ...cause(provider) });
+    const failure = (message, provider) => {
         const classified = classify(message);
         if (classified.kind === 'signed-out')
             ctx.invalidateAuth?.();
-        return { ok: false, ...classified, message };
+        return { ok: false, ...classified, message, ...classified.kind === 'signed-out' ? cause(provider) : {} };
     };
     const execute = async (spec, on, keyAgent, preparedOutput) => {
         // Member boundary first: a member never speaks in another member's session, refused before any request. A key
@@ -268,7 +271,7 @@ export function createRuns(ctx) {
                 try {
                     on?.({ type: 'account', account: pick.account.id, model: pick.model, sessionKey, how: pick.how, why: pick.why, considered: pick.considered });
                     if (!ready)
-                        return { ok: false, kind: 'signed-out', message: `${pick.account.name} is not signed in` };
+                        return signedOut(pick.account.provider, `${pick.account.name} is not signed in`);
                     return await start(spec, on, { agentId: agent, sessionKey, idempotencyKey, system,
                         picked: pick.model ? await accountOf(pick.model) : undefined, output, chosen: pick }); // '' = no override
                 }
@@ -359,7 +362,7 @@ export function createRuns(ctx) {
                     return { ok: false, kind: 'other', message: String(auth.unavailable.message ?? 'account status unavailable') };
                 const row = (auth.providers ?? []).find((e) => (typeof e === 'string' ? e : e?.provider) === picked.provider);
                 if (!row || !usable(row))
-                    return { ok: false, kind: 'signed-out', message: `${picked.provider} is not signed in for ${spec.member}` };
+                    return signedOut(picked.provider, `${picked.provider} is not signed in for ${spec.member}`);
             }
             // One `agent` request: its interim `accepted` frame names the run, its final frame (after the run) carries the
             // run's usage. The wait below still decides how the run ended. Thinking is clamped to the catalog before the
@@ -425,11 +428,11 @@ export function createRuns(ctx) {
                 return { ok: false, aborted: true };
             const message = typeof result.error === 'string' ? result.error
                 : typeof result.message === 'string' ? result.message : '';
-            return failure(message);
+            return failure(message, picked?.provider);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            return failure(message);
+            return failure(message, picked?.provider);
         }
         finally {
             ended = true;

package/dist/signin.d.ts

@@ -1,6 +1,6 @@
 import type { remoteCliHost } from '@byokit/accounts/cli';
 import { authStatus } from './auth-status.ts';
-import type { GatewayTransport, Member, SignInOptions, SignInView } from './types.ts';
+import type { CliLoginCause, GatewayTransport, Member, SignInOptions, SignInView } from './types.ts';
 export type SignInCtx = {
     request: GatewayTransport['request'];
     authStatus?: (agentId: string, refresh: boolean, native: boolean) => ReturnType<typeof authStatus>;
@@ -10,7 +10,7 @@ export type SignInCtx = {
     callbackPort: number;
     nativeClaudeLogin?(): ReturnType<typeof remoteCliHost>;
     resetNativeClaudeLogin?(): Promise<void>;
-    claudeLoginUnread?(): boolean;
+    claudeLogin?(): CliLoginCause;
     onDisconnect?(fn: () => void): () => void;
     authConfig(): string;
     restarted(authBefore: string | undefined, signal?: AbortSignal): Promise<boolean>;

package/dist/signin.js

@@ -241,8 +241,9 @@ export function signIn(ctx, member, o, on) {
                 };
                 native = ctx.nativeClaudeLogin?.();
                 if (!await detected()) {
-                    if (ctx.claudeLoginUnread?.())
-                        return { state: 'failed', via, why: 'failed', error: 'Claude Code is installed here, but its sign-in could not be checked. Run claude once on this machine to sign in, then try again.' };
+                    const cause = ctx.claudeLogin?.();
+                    if (cause?.signIn === false)
+                        return { state: 'failed', via, why: 'failed', error: 'Claude Code is installed here, but its sign-in could not be checked. Run claude once on this machine to sign in, then try again.', cause };
                     if (!native)
                         return { state: 'failed', via, why: 'failed', error: 'Claude Code sign-in is not available on this engine.' };
                     let started = await native.start('claude', { signal });

package/dist/types.d.ts

@@ -180,6 +180,18 @@ export type RunEnd<T = unknown> = {
     kind: 'signed-out' | 'resting' | 'plan' | 'network' | 'other' | 'output';
     until?: number;
     message: string;
+    cause?: CliLoginCause;
+};
+/** Why a `claude-cli` run or `anthropic-cli` sign-in failed: Claude Code has no login where this engine reads it (5.5).
+ * `signIn` true: `signIn(member, { authChoice: 'anthropic-cli' })` runs that login into `configDir` (subscription
+ * billing, the person's Claude plan). False: the engine reads the person's own login, which the kit never writes; the
+ * person runs `claude` on this machine, as `home`, to sign in (`configDir` only when they set CLAUDE_CONFIG_DIR). */
+export type CliLoginCause = {
+    code: 'needs_cli_login';
+    cli: 'claude';
+    home: string;
+    configDir?: string;
+    signIn: boolean;
 };
 export type SignInOptions = {
     authChoice: string;
@@ -196,6 +208,7 @@ export type SignInView = {
     prompt?: string;
     error?: string;
     why?: 'busy' | 'declined' | 'expired' | 'failed';
+    cause?: CliLoginCause;
 };
 export type Approval = {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",