@alfe.ai/claude-code-host 0.1.15 → 0.1.16

package/dist/index.cjs

@@ -5,25 +5,35 @@ exports.BRIDGE_ENV_VAR = require_host_config.BRIDGE_ENV_VAR;
 exports.CLAUDE_PERMISSION_MODES = require_host_config.CLAUDE_PERMISSION_MODES;
 exports.CREDENTIAL_ENV_VAR = require_host_config.CREDENTIAL_ENV_VAR;
 exports.CREDENTIAL_INVALID_MESSAGE = require_host_config.CREDENTIAL_INVALID_MESSAGE;
-exports.CREDENTIAL_MISSING_MESSAGE = require_host_config.CREDENTIAL_MISSING_MESSAGE;
 exports.CREDENTIAL_UNAVAILABLE_MESSAGE = require_host_config.CREDENTIAL_UNAVAILABLE_MESSAGE;
 exports.ClaudeCodeHost = require_host_config.ClaudeCodeHost;
 exports.CredentialStatusReporter = require_host_config.CredentialStatusReporter;
 exports.DEFAULT_ALLOWED_TOOLS = require_host_config.DEFAULT_ALLOWED_TOOLS;
+exports.DEFAULT_LOCAL_AI_PROXY_URL = require_host_config.DEFAULT_LOCAL_AI_PROXY_URL;
 exports.DEFAULT_PERMISSION_MODE = require_host_config.DEFAULT_PERMISSION_MODE;
-exports.LOCAL_LOGIN_FAILED_MESSAGE = require_host_config.LOCAL_LOGIN_FAILED_MESSAGE;
+exports.LOCAL_LOGIN_REFUSED_MESSAGE = require_host_config.LOCAL_LOGIN_REFUSED_MESSAGE;
+exports.LOCAL_LOGIN_SWITCHED_MESSAGE = require_host_config.LOCAL_LOGIN_SWITCHED_MESSAGE;
 exports.MANAGED_ALLOWED_TOOLS = require_host_config.MANAGED_ALLOWED_TOOLS;
 exports.MANAGED_DISALLOWED_TOOLS = require_host_config.MANAGED_DISALLOWED_TOOLS;
+exports.MODEL_UNAVAILABLE_MESSAGE = require_host_config.MODEL_UNAVAILABLE_MESSAGE;
+exports.OUT_OF_CREDITS_MESSAGE = require_host_config.OUT_OF_CREDITS_MESSAGE;
+exports.PROXY_AGENT_MODEL_ENV_VARS = require_host_config.PROXY_AGENT_MODEL_ENV_VARS;
+exports.PROXY_API_KEY_PLACEHOLDER = require_host_config.PROXY_API_KEY_PLACEHOLDER;
+exports.PROXY_AUTH_FAILED_MESSAGE = require_host_config.PROXY_AUTH_FAILED_MESSAGE;
+exports.PROXY_DEFAULT_MODEL = require_host_config.PROXY_DEFAULT_MODEL;
+exports.PROXY_MODEL_ENV = require_host_config.PROXY_MODEL_ENV;
 exports.SCRUBBED_ANTHROPIC_ENV_VARS = require_host_config.SCRUBBED_ANTHROPIC_ENV_VARS;
 exports.STATUS_REPORT_INTERVAL_MS = require_host_config.STATUS_REPORT_INTERVAL_MS;
 exports.SessionDriver = require_host_config.SessionDriver;
 exports.TERMINATION_GRACE_MS = require_host_config.TERMINATION_GRACE_MS;
 exports.TURN_TIMEOUT_MS = require_host_config.TURN_TIMEOUT_MS;
+exports.USAGE_LIMIT_MESSAGE = require_host_config.USAGE_LIMIT_MESSAGE;
 exports.WARM_STREAMING_SUPPORTED = require_host_config.WARM_STREAMING_SUPPORTED;
 exports.addMessage = require_host_config.addMessage;
 exports.appendActivity = require_host_config.appendActivity;
 exports.buildChildEnv = require_host_config.buildChildEnv;
 exports.buildProbeArgs = require_host_config.buildProbeArgs;
+exports.classifyProxyDenial = require_host_config.classifyProxyDenial;
 exports.collectTurnActivityRecords = require_host_config.collectTurnActivityRecords;
 exports.createMapperState = require_host_config.createMapperState;
 exports.createSession = require_host_config.createSession;

package/dist/index.d.cts

@@ -862,11 +862,21 @@ interface AgentClaudeCredential {
   revision: string;
   updatedAt: string;
 }
-/** Claude auth health a claude-code host reports for its agent. */
+/**
+ * Claude auth health a claude-code host reports for its agent. `missing` is
+ * legacy: hosts since the AI-proxy fallback (2026-10-15) never send it.
+ */
 type ClaudeCredentialHealth = "ok" | "missing" | "invalid";
+/**
+ * Which auth the host's turns run on: the stored credential, the machine's
+ * own `claude` login (self-hosted only), or the Alfe AI proxy (Alfe credits).
+ */
+type ClaudeCredentialSource = "credential" | "local_login" | "ai_proxy";
 /** Body of PUT /agent/claude-credential/status. */
 interface ClaudeCredentialStatusReport {
   status: ClaudeCredentialHealth;
+  /** The auth source the status describes. Omitted only by older hosts. */
+  source?: ClaudeCredentialSource;
   /** Short (≤200 chars), fixed host-side explanation. Never `claude` output or a secret. */
   detail?: string;
   /**
@@ -894,8 +904,8 @@ declare class WorkspaceApi extends ApiBase {
   }>;
   /**
    * GET /agent/claude-credential — the authenticated claude-code agent's own
-   * Claude credential, or `null` when none is stored (a self-hosted host then
-   * falls back to the local `claude` login). Fetch on every runtime start: the
+   * Claude credential, or `null` when none is stored (the host then falls back
+   * to the local `claude` login when self-hosted, else the Alfe AI proxy). Fetch on every runtime start: the
    * daemon restarts the host whenever the credential changes.
    */
   getClaudeCredential(): Promise<AgentClaudeCredential | null>;
@@ -2271,22 +2281,35 @@ declare class ChatServiceClient {
 /**
  * Child-process environment construction for spawned `claude` CLI processes.
  *
- * THREE non-negotiable invariants:
+ * Every turn runs on exactly ONE auth source (`ChildAuth`), resolved by the
+ * host (see DEVELOPING.md "Auth source resolution"):
+ *
+ *  - `credential`  — the agent's stored Claude credential, set as exactly one
+ *    variable: `CLAUDE_CODE_OAUTH_TOKEN` (subscription token from
+ *    `claude setup-token`) or `ANTHROPIC_API_KEY` (Anthropic API key).
+ *  - `local_login` — self-hosted only: no auth variable, so `claude` uses the
+ *    machine's own login (and whatever provider the operator configured).
+ *  - `ai_proxy`    — the Alfe AI proxy via the daemon's loopback proxy:
+ *    `ANTHROPIC_BASE_URL` = the local proxy, `ANTHROPIC_AUTH_TOKEN` = a
+ *    placeholder the local proxy replaces with the daemon's agent key, and
+ *    every model alias pinned to an Alfe registry id (the proxy routes exact
+ *    registry ids only; the CLI's built-in aliases resolve to dated ids that
+ *    are a 409 there).
+ *
+ * Invariants:
  *
  * 1. **Scrub inherited Claude auth.** `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`
  *    / `ANTHROPIC_AUTH_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` are removed from BOTH
  *    the parent env and any caller `extra`. A self-hosted Mac very often has
  *    these set for other tooling; if one reaches `claude` it silently switches
- *    accounts or billing plane (or routes through a proxy). The break is
- *    silent: the turn "works" but bills the wrong account.
+ *    accounts or billing plane. Credential and proxy modes also drop provider
+ *    overrides (Bedrock/Vertex/Foundry); proxy mode additionally drops model
+ *    and header overrides so nothing reaches the proxy that it cannot price.
  *
- * 2. **Inject the agent's own credential, last.** When the agents service holds
- *    a Claude credential for this agent, it is set AFTER the scrub as exactly
- *    one variable: `CLAUDE_CODE_OAUTH_TOKEN` (subscription token from
- *    `claude setup-token`) or `ANTHROPIC_API_KEY` (Anthropic API key). Nothing
- *    else can override it. With no credential, no auth variable is set and
- *    `claude` uses the machine's own login (self-hosted fallback). The value
- *    lives only in the host's memory and this env — never on disk, never logged.
+ * 2. **Inject the source last.** Nothing in `base` or `extra` can override the
+ *    injected credential or proxy settings. A credential lives only in the
+ *    host's memory and this env, never on disk, never logged. Proxy settings
+ *    never appear in a credential or local-login env.
  *
  * 3. **Set `ALFE_CLAUDE_BRIDGE=1`.** The Phase-1 CLI hooks
  *    (`alfe claude hook ...` in `packages/cli/src/commands/claude.ts`) check
@@ -2299,14 +2322,55 @@ declare class ChatServiceClient {
 declare const SCRUBBED_ANTHROPIC_ENV_VARS: readonly ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"];
 /**
  * Provider-selection and endpoint overrides that would route `claude` away from
- * the Anthropic API. Dropped whenever an agent credential is injected, so an
- * inherited `CLAUDE_CODE_USE_BEDROCK=1` (say) can't send the turn to Bedrock
- * and ignore the stored credential. Without a credential they are left alone:
- * the machine's own `claude` setup is the fallback, whatever provider it uses.
+ * the Anthropic API. Dropped whenever a credential or the AI proxy is in use,
+ * so an inherited `CLAUDE_CODE_USE_BEDROCK=1` (say) can't send the turn to
+ * Bedrock and ignore the chosen source. On a local login they are left alone:
+ * the machine's own `claude` setup is the source, whatever provider it uses.
  */
 
 /** Cross-phase contract marker (see header + packages/cli/src/commands/claude.ts). */
 declare const BRIDGE_ENV_VAR = "ALFE_CLAUDE_BRIDGE";
+/**
+ * Placeholder `ANTHROPIC_AUTH_TOKEN` (sent as `Authorization: Bearer`) for
+ * proxy mode. `@alfe.ai/ai-proxy-local` keeps an incoming `alfe_…` key and
+ * replaces anything else with the daemon's agent key (as `x-api-key`, dropping
+ * `authorization`), so the agent key itself never enters the `claude` env (a
+ * managed agent has Bash). Never `alfe_…`.
+ */
+declare const PROXY_API_KEY_PLACEHOLDER = "alfe-local-proxy";
+/**
+ * Default local AI proxy (`DEFAULT_AI_PROXY_PORT` in `@alfe.ai/ai-proxy-local`).
+ * The daemon passes the URL it actually bound as `ALFE_LOCAL_AI_PROXY_URL`;
+ * this is the fallback. Bare host, no `/v1`: `claude` appends `/v1/messages`.
+ */
+declare const DEFAULT_LOCAL_AI_PROXY_URL = "http://127.0.0.1:18193";
+/**
+ * The model `claude -p --model` runs in proxy mode when the agent has no
+ * `defaultModel` (or the daemon's lookup timed out). `claude`'s own default is
+ * a dated id the proxy cannot route. Haiku 4.5 is the one Claude model seeded
+ * on every stage (the memory integration depends on it), so it is the only
+ * id guaranteed to route; the dashboard always sets a model, so this is rare.
+ */
+declare const PROXY_DEFAULT_MODEL = "claude-haiku-4-5";
+/**
+ * Fixed model env in proxy mode, Alfe registry ids (`AnthropicModel` in
+ * `@alfe/types`; the child-env test asserts it). `ANTHROPIC_SMALL_FAST_MODEL`
+ * drives background calls (titles, summaries); `ANTHROPIC_DEFAULT_HAIKU_MODEL`
+ * resolves the `haiku` alias. Haiku 4.5 because it is seeded on every stage.
+ * claude 2.1.284/2.1.287 read these and {@link PROXY_AGENT_MODEL_ENV_VARS}.
+ */
+declare const PROXY_MODEL_ENV: {
+  readonly ANTHROPIC_SMALL_FAST_MODEL: "claude-haiku-4-5";
+  readonly ANTHROPIC_DEFAULT_HAIKU_MODEL: "claude-haiku-4-5";
+};
+/**
+ * The `sonnet` / `opus` aliases (subagents) resolve to the agent's OWN model
+ * in proxy mode: the agents service validated it against the registry, while a
+ * fixed 5.x id may not be enabled on the workspace.
+ */
+declare const PROXY_AGENT_MODEL_ENV_VARS: readonly ["ANTHROPIC_DEFAULT_SONNET_MODEL", "ANTHROPIC_DEFAULT_OPUS_MODEL"];
+/** Set only in proxy mode (besides the auth pair). */
+
 /** The agent's Claude credential, as fetched from `GET /agent/claude-credential`. */
 interface ChildCredential {
   kind: 'oauth_token' | 'api_key';
@@ -2314,16 +2378,29 @@ interface ChildCredential {
 }
 /** The single env var each credential kind is exported as. */
 declare const CREDENTIAL_ENV_VAR: Record<ChildCredential['kind'], string>;
+/** The auth source of one `claude` child. */
+type ChildAuth = {
+  mode: 'credential';
+  credential: ChildCredential;
+} | {
+  mode: 'local_login';
+}
+/** `model` = the turn's registry model id (`--model`); also the sonnet/opus aliases. */ | {
+  mode: 'ai_proxy';
+  baseUrl: string;
+  model: string;
+};
 /**
  * Build the env handed to a spawned `claude` child. Pure — takes the base env
  * explicitly so it unit-tests without touching `process.env`.
  *
  * Order: merge `base` + `extra` → drop every scrubbed var (plus provider
- * overrides when a credential is injected) → set the bridge
- * marker → set the agent credential (if any). Neither `base` nor `extra` can
- * smuggle an auth variable in or override the injected credential.
+ * overrides for a credential or the proxy, plus model overrides for the
+ * proxy) → set the bridge marker → set the source's variables. Neither `base`
+ * nor `extra` can smuggle an auth variable in or override the source.
+ * `auth` omitted = local login.
  */
-declare function buildChildEnv(base: NodeJS.ProcessEnv, extra?: Record<string, string>, credential?: ChildCredential | null): NodeJS.ProcessEnv;
+declare function buildChildEnv(base: NodeJS.ProcessEnv, extra?: Record<string, string>, auth?: ChildAuth): NodeJS.ProcessEnv;
 //#endregion
 //#region src/stream-mapper.d.ts
 /**
@@ -2421,6 +2498,11 @@ interface EndEmission {
    * message). Present only on error turns.
    */
   authFailed?: true;
+  /**
+   * The refusal was a 403 (forbidden: an org or provider policy), not a dead
+   * login or key. Present only with `authFailed`.
+   */
+  authForbidden?: true;
 }
 type MapperEmission = ActivityEmission | TextEmission | EndEmission;
 interface PendingTool {
@@ -2535,6 +2617,8 @@ interface DriverTurnResult {
   aborted: boolean;
   /** Present (true) when the turn failed because Claude refused the credential. */
   authFailed?: true;
+  /** With `authFailed`: the refusal was a 403 (policy), not a dead login/key. */
+  authForbidden?: true;
 }
 interface RunTurnParams {
   /** The user prompt for this turn. */
@@ -2547,7 +2631,10 @@ interface RunTurnParams {
   mcpConfigPath?: string;
   /** Persona + reply-style text appended to the system prompt. Omitted → none. */
   appendSystemPrompt?: string;
-  /** Bare Claude model id for `--model` (subscription models only). Omitted → CLI default. */
+  /**
+   * Bare Claude model id for `--model`. Omitted → CLI default (never in proxy
+   * mode: the host always passes a registry id there).
+   */
   model?: string;
   /** Tool allow-list (defaults to DEFAULT_ALLOWED_TOOLS). */
   allowedTools?: readonly string[];
@@ -2580,7 +2667,7 @@ declare class SessionDriver {
   private abortCurrent;
   private readonly bin;
   private readonly baseEnv;
-  private readonly credential;
+  private readonly auth;
   private readonly managed;
   private readonly log;
   /** Injected spawn — tests replace this with a fake child. */
@@ -2589,10 +2676,10 @@ declare class SessionDriver {
     claudeBin?: string;
     baseEnv?: NodeJS.ProcessEnv;
     /**
-     * The agent's Claude credential, injected into the child env after the
-     * scrub. Null/absent → the machine's own `claude` login.
+     * The turn's auth source, applied to the child env after the scrub
+     * (`buildChildEnv`). Absent → the machine's own `claude` login.
      */
-    credential?: ChildCredential | null;
+    auth?: ChildAuth;
     /** Managed VM: Bash allowed + deny rules (see MANAGED_ALLOWED_TOOLS). */
     managed?: boolean;
     logger?: Logger;
@@ -2638,22 +2725,46 @@ declare function loadCredentialWithRetry(fetchCredential: () => Promise<HostCred
   credential: HostCredential | null;
 } | null>;
 declare function isAuthFailureText(text: string): boolean;
+/** Why the Alfe AI proxy refused a request it otherwise authenticated. */
+type ProxyDenial = 'credits' | 'usage_limit' | 'model_unavailable';
+/**
+ * Classify an Alfe AI proxy refusal from the text `claude` reports. The proxy
+ * answers credit and usage-limit denials on `/v1/messages` with a 429
+ * `rate_limit_error` (never 402, see services/ai DEVELOPING.md "Credit denials
+ * on LLM routes are 429"); claude 2.1.287 surfaces it as
+ * `API Error: Request rejected (429) · <message>` (fixture
+ * `turn-proxy-credits.stream.jsonl`). Credit texts also say "usage limit
+ * reached", so they are checked first. An Anthropic subscription limit
+ * ("Claude AI usage limit reached") is not an Alfe denial.
+ */
+declare function classifyProxyDenial(text: string): ProxyDenial | null;
 /** HTTP statuses on a `result` event that mean "credential refused". */
 
 type ProbeOutcome = {
   result: 'ok';
-} | {
+}
+/** `forbidden`: a 403 (an org or provider policy), not a dead login or key. */ | {
   result: 'invalid';
+  forbidden?: true;
+}
+/** The Alfe AI proxy authenticated the agent but refused the request. */ | {
+  result: 'denied';
+  denial: ProxyDenial;
 } | {
   result: 'unknown';
   reason: string;
 };
 declare const AUTH_PROBE_TIMEOUT_MS = 60000;
-/** argv for the probe. No tools, no session file, no MCP, no settings files. */
-declare function buildProbeArgs(): string[];
+/**
+ * argv for the probe. No tools, no session file, no MCP, no settings files.
+ * `model` is `haiku` (the alias) on a credential or local login, and the
+ * registry Haiku id through the AI proxy.
+ */
+declare function buildProbeArgs(model?: string): string[];
 declare function parseProbeOutput(stdout: string, stderr: string, exitCode: number | null): ProbeOutcome;
 interface AuthProbeOptions {
-  credential: ChildCredential | null;
+  /** The auth source to check (a credential, the local login, or the AI proxy). */
+  auth: ChildAuth;
   baseEnv: NodeJS.ProcessEnv;
   /** Any existing directory; the probe reads and writes nothing there. */
   cwd: string;
@@ -2664,12 +2775,17 @@ interface AuthProbeOptions {
   signal?: AbortSignal;
 }
 /**
- * One minimal real turn against Anthropic with the agent's credential (or,
- * when none is stored, the machine's own login). Never throws.
+ * One minimal real turn on the given auth source: Anthropic with the agent's
+ * credential or the machine's own login, or the Alfe AI proxy (a Haiku ping
+ * billed from Alfe credits). Never throws.
  */
 declare function runAuthProbe(opts: AuthProbeOptions): Promise<ProbeOutcome>;
+/** Which auth the host's turns run on (projected as `claudeCredentialSource`). */
+type CredentialSource = 'credential' | 'local_login' | 'ai_proxy';
 interface CredentialStatusReport {
+  /** `missing` is legacy; this host never sends it (it falls back to the AI proxy). */
   status: 'ok' | 'missing' | 'invalid';
+  source?: CredentialSource;
   /** Fixed, host-authored text only. Never `claude` output. */
   detail?: string;
   revision?: string;
@@ -2715,21 +2831,31 @@ interface ClaudeCodeHostConfig {
   /**
    * Bare Claude model id for `claude -p --model` (e.g. `claude-opus-4-8` or the
    * `opus`/`sonnet`/`haiku` aliases). Sourced from the agent's `defaultModel`
-   * via `ALFE_DEFAULT_MODEL`. Omitted → the operator's `claude` CLI default.
+   * via `ALFE_DEFAULT_MODEL`. Omitted → the operator's `claude` CLI default on
+   * a credential or local login, `PROXY_DEFAULT_MODEL` on the AI proxy.
    * NEVER provider-qualified (`anthropic/…`) — that's an OpenClaw-only shape.
    */
   model?: string;
   /**
-   * Managed VM (`ALFE_MANAGED=1|true`, set by the daemon). Enables Bash, and a
-   * missing Claude credential is a hard "missing" state (no local login to
-   * fall back to). Self-hosted when false/absent.
+   * Managed VM (`ALFE_MANAGED=1|true`, set by the daemon). Enables Bash. With
+   * no stored credential a managed agent always runs on the Alfe AI proxy (no
+   * local login to fall back to). Self-hosted when false/absent.
    */
   managed?: boolean;
+  /**
+   * The daemon's loopback AI proxy (`ALFE_LOCAL_AI_PROXY_URL`). Defaults to
+   * `DEFAULT_LOCAL_AI_PROXY_URL`.
+   */
+  localAiProxyUrl?: string;
   logger?: Logger;
 }
 declare const CREDENTIAL_INVALID_MESSAGE = "This agent's Claude credential is invalid or expired. Update it in agent settings.";
-declare const LOCAL_LOGIN_FAILED_MESSAGE = "Claude Code is not signed in on this machine. Run `claude` and log in, or add a Claude credential in agent settings.";
-declare const CREDENTIAL_MISSING_MESSAGE = "This agent has no Claude credential. Add a Claude subscription token or an Anthropic API key in agent settings.";
+declare const OUT_OF_CREDITS_MESSAGE = "This agent is out of Alfe credits. Add credits in Alfe Billing, or add a Claude credential in agent settings, then resend your message.";
+declare const USAGE_LIMIT_MESSAGE = "This agent hit an Alfe usage limit. Raise the limit in Alfe or wait for it to reset, then resend your message.";
+declare const LOCAL_LOGIN_SWITCHED_MESSAGE = "Your machine's Claude login stopped working, so this agent switched to Alfe credits. Please resend your message.";
+declare const LOCAL_LOGIN_REFUSED_MESSAGE = "Claude refused this machine's claude login (403). Check the account or its organisation policy, or add a Claude credential in agent settings.";
+declare const MODEL_UNAVAILABLE_MESSAGE = "This agent's model isn't available on this workspace. Choose another Claude model in agent settings, then resend your message.";
+declare const PROXY_AUTH_FAILED_MESSAGE = "Alfe AI rejected this agent's key. Reconnect the agent (run `alfe setup` on its machine), or add a Claude credential in agent settings.";
 declare const CREDENTIAL_UNAVAILABLE_MESSAGE = "This agent's Claude credential couldn't be loaded yet. Try again in a moment.";
 /** How long a turn waits for the start-up credential fetch before failing. */
 
@@ -2768,8 +2894,16 @@ declare class ClaudeCodeHost {
   /** Turns waiting for the credential, before queue admission (chat.abort). */
   private readonly waitingTurns;
   private readonly loaderRestartMs;
+  /** How often a fallen-back self-hosted agent re-checks its local login. */
+  private readonly localLoginRecheckMs;
+  private localLoginRecheck;
   /** In memory only. Never logged, never persisted. */
   private credential;
+  /**
+   * The auth every new turn runs on, resolved once the credential fetch
+   * answers (see `resolveAuthSource`). Null before that.
+   */
+  private authSource;
   private readonly credentialAbort;
   private readonly reporter;
   private readonly probe;
@@ -2777,17 +2911,22 @@ declare class ClaudeCodeHost {
   private readonly credentialRetry;
   constructor(cfg: ClaudeCodeHostConfig, deps?: {
     /**
-     * Per-turn driver factory (test seam). Called once per turn with the
-     * agent's credential (null → the machine's own `claude` login).
+     * Per-turn driver factory (test seam). Called once per turn (and once
+     * more for a local-login turn re-run on the AI proxy) with its auth.
      */
-    makeDriver?: (credential: ChildCredential | null) => SessionDriver;
+    makeDriver?: (auth: ChildAuth) => SessionDriver;
     chat?: ChatServiceClient;
     api?: AgentApiClient;
     /** Start-up auth check (test seam; default: a minimal `claude -p`). */
-    probe?: (credential: ChildCredential | null, signal: AbortSignal) => Promise<ProbeOutcome>;
+    probe?: (auth: ChildAuth, signal: AbortSignal) => Promise<ProbeOutcome>;
     credentialWaitMs?: number;
     /** Delay before restarting a credential loader that threw (default 5 s). */
     loaderRestartMs?: number;
+    /**
+     * After falling back from a refused local login, re-probe it this often
+     * and switch back when it works (default: the status-report interval).
+     */
+    localLoginRecheckMs?: number;
     credentialRetry?: {
       baseDelayMs?: number;
       maxDelayMs?: number;
@@ -2801,11 +2940,33 @@ declare class ClaudeCodeHost {
    */
   private runCredentialLoader;
   private loadCredential;
-  private childCredential;
-  /** Start-up health check: one minimal real call, reported to the cloud. */
+  /**
+   * A method, not a property read: `stopping` flips across awaits, which
+   * control-flow narrowing cannot see.
+   */
+  private isStopping;
+  /** Same reason as `isStopping`: `authSource` can change across an await. */
+  private currentAuthSource;
+  /** The auth a new turn runs on. Local login until the fetch has answered. */
+  private childAuth;
+  /**
+   * A self-hosted agent with no credential whose local login was refused (401
+   * or an explicit auth message, never a 403): run new turns through the Alfe
+   * AI proxy, and re-check the login periodically so a re-login moves the agent
+   * back off Alfe credits. Never for a stored credential (the user chose it; a
+   * refusal there needs their fix) and never on managed.
+   */
+  private fallBackToProxy;
+  private scheduleLocalLoginRecheck;
+  /** While fallen back: one local-login probe; back to the login when it works. */
+  private recheckLocalLogin;
+  /**
+   * Start-up check: one minimal real call on the resolved source, reported to
+   * the cloud. A refused local login falls back to the proxy and checks that.
+   */
   private checkCredential;
-  /** Report the credential (or the local login) as working or refused. */
-  private reportAuth;
+  /** Report the current auth source as working or refused. */
+  private reportStatus;
   /**
    * Wait for the first credential answer BEFORE queue admission, so a waiting
    * turn holds no slot. Bounded by the start-up deadline: once it has passed,
@@ -2829,6 +2990,13 @@ declare class ClaudeCodeHost {
   private handleAgent;
   private deliverAgentOutcome;
   private runAgentTurn;
+  /**
+   * Settle a failed turn (C3) after storing its message as the assistant's
+   * reply, so the history shows what the user saw. Stored first: a client that
+   * reloads on the failure must find it. Best-effort: a store failure never
+   * changes the outcome.
+   */
+  private failTurn;
   /**
    * Send every message the memory service has not accepted yet. Indices are
    * the messages' positions in the session file, so they advance across turns
@@ -2854,6 +3022,12 @@ declare class ClaudeCodeHost {
    * Run a turn; on a `--resume` failure (stale/missing claude session id) start
    * fresh and prepend the last-N stored messages so the model keeps context.
    */
+  /**
+   * Run one turn on `auth` with its own driver, registered as the session's
+   * running turn so `chat.abort` reaches it. Proxy turns always carry a
+   * registry model.
+   */
+  private runTurnOn;
   private runWithResumeFallback;
   private forwardEmission;
   private handleChatAbort;
@@ -2901,6 +3075,12 @@ interface ChatMessage {
   role: 'user' | 'assistant';
   content: string;
   timestamp: number;
+  /**
+   * `'error'`: the failure message a turn settled with, stored so the history
+   * shows what the user saw. History only: memory ingest and the resume
+   * preamble skip it (it is not something the agent said).
+   */
+  kind?: 'error';
   senderId?: string;
   senderName?: string;
   components?: StoredMessageComponent[];
@@ -2936,7 +3116,10 @@ type ChatActivityRecord = {
 interface SessionData {
   sessionId: string;
   agentId: string;
+  /** Always `CHAT_SESSION_CHANNEL` for sessions this host writes. */
   channel: string;
+  /** The chat surface that opened the conversation (`mobile`, `dashboard`, ...). */
+  clientType?: string;
   tenantId?: string;
   userId?: string;
   createdAt: string;
@@ -2979,21 +3162,24 @@ interface SessionSummary {
   preview?: string;
   messageCount: number;
 }
+/**
+ * The channel every chat session is stored on. Every chat client lists with
+ * `sessions.list { channel: 'alfe' }` and openclaw-chat stores `'alfe'`, so any
+ * other value hides the conversation from the rail.
+ */
+
 declare function getSession(sessionId: string): Promise<SessionData | null>;
 declare function saveSession(session: SessionData): Promise<void>;
-declare function createSession(sessionId: string, agentId: string, channel: string, tenantId?: string, userId?: string): Promise<SessionData>;
+declare function createSession(sessionId: string, agentId: string, channel: string, tenantId?: string, userId?: string, clientType?: string): Promise<SessionData>;
 /**
  * Append a message. Returns its index (position in `messages`), the stable
  * memory-ingest index, or -1 when the session does not exist.
  */
 declare function addMessage(sessionId: string, role: 'user' | 'assistant', content: string, senderId?: string, senderName?: string, components?: StoredMessageComponent[], attachments?: StoredAttachment[]): Promise<number>;
 /**
- * Memory ingest bounds, in serialised UTF-8 bytes. The ingest endpoint
- * forwards the whole body as ONE SQS message and trims the OLDEST messages
- * past 250,000 bytes (`services/memory/api-agents/ingest/fit-batch.ts`); a
- * trimmed head is lost for good because the consumer's watermark jumps past
- * it. Staying well under that limit means the server never trims. Bytes, not
- * characters: one CJK character is three UTF-8 bytes.
+ * Store the failure message a turn settled with as the assistant's reply, so
+ * the history shows what the user saw. Returns its index, or -1 when the
+ * session does not exist.
  */
 
 /**
@@ -3015,4 +3201,4 @@ declare function listSessions(filters?: {
  */
 declare function resolveHostConfig(): ClaudeCodeHostConfig;
 //#endregion
-export { AUTH_PROBE_TIMEOUT_MS, type ActivityEmission, BRIDGE_ENV_VAR, CLAUDE_PERMISSION_MODES, CREDENTIAL_ENV_VAR, CREDENTIAL_INVALID_MESSAGE, CREDENTIAL_MISSING_MESSAGE, CREDENTIAL_UNAVAILABLE_MESSAGE, type ChatActivityRecord, type ChatMessage, type ChildCredential, ClaudeCodeHost, type ClaudeCodeHostConfig, type ClaudePermissionMode, type CredentialStatusReport, CredentialStatusReporter, DEFAULT_ALLOWED_TOOLS, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type HostCredential, LOCAL_LOGIN_FAILED_MESSAGE, MANAGED_ALLOWED_TOOLS, MANAGED_DISALLOWED_TOOLS, type MapperEmission, type MapperState, type ProbeOutcome, type RunTurnParams, SCRUBBED_ANTHROPIC_ENV_VARS, STATUS_REPORT_INTERVAL_MS, type SessionData, SessionDriver, type SessionSummary, TERMINATION_GRACE_MS, TURN_TIMEOUT_MS, type TextEmission, type ThinkingActivity, type ToolActivity, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, buildProbeArgs, collectTurnActivityRecords, createMapperState, createSession, getSession, isAuthFailureText, listSessions, loadCredentialWithRetry, mapStreamEvent, mapStreamEvents, parseProbeOutput, resolveHostConfig, runAuthProbe, saveSession, stripAgentPrefix };
+export { AUTH_PROBE_TIMEOUT_MS, type ActivityEmission, BRIDGE_ENV_VAR, CLAUDE_PERMISSION_MODES, CREDENTIAL_ENV_VAR, CREDENTIAL_INVALID_MESSAGE, CREDENTIAL_UNAVAILABLE_MESSAGE, type ChatActivityRecord, type ChatMessage, type ChildAuth, type ChildCredential, ClaudeCodeHost, type ClaudeCodeHostConfig, type ClaudePermissionMode, type CredentialSource, type CredentialStatusReport, CredentialStatusReporter, DEFAULT_ALLOWED_TOOLS, DEFAULT_LOCAL_AI_PROXY_URL, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type HostCredential, LOCAL_LOGIN_REFUSED_MESSAGE, LOCAL_LOGIN_SWITCHED_MESSAGE, MANAGED_ALLOWED_TOOLS, MANAGED_DISALLOWED_TOOLS, MODEL_UNAVAILABLE_MESSAGE, type MapperEmission, type MapperState, OUT_OF_CREDITS_MESSAGE, PROXY_AGENT_MODEL_ENV_VARS, PROXY_API_KEY_PLACEHOLDER, PROXY_AUTH_FAILED_MESSAGE, PROXY_DEFAULT_MODEL, PROXY_MODEL_ENV, type ProbeOutcome, type ProxyDenial, type RunTurnParams, SCRUBBED_ANTHROPIC_ENV_VARS, STATUS_REPORT_INTERVAL_MS, type SessionData, SessionDriver, type SessionSummary, TERMINATION_GRACE_MS, TURN_TIMEOUT_MS, type TextEmission, type ThinkingActivity, type ToolActivity, USAGE_LIMIT_MESSAGE, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, buildProbeArgs, classifyProxyDenial, collectTurnActivityRecords, createMapperState, createSession, getSession, isAuthFailureText, listSessions, loadCredentialWithRetry, mapStreamEvent, mapStreamEvents, parseProbeOutput, resolveHostConfig, runAuthProbe, saveSession, stripAgentPrefix };