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

package/dist/host-config.cjs

@@ -13,22 +13,35 @@ let _alfe_ai_config = require("@alfe.ai/config");
 /**
 * 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
@@ -46,10 +59,10 @@ const SCRUBBED_ANTHROPIC_ENV_VARS = [
 ];
 /**
 * 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.
 */
 const PROVIDER_OVERRIDE_ENV_VARS = [
 	"CLAUDE_CODE_USE_BEDROCK",
@@ -68,6 +81,60 @@ const PROVIDER_OVERRIDE_ENV_VARS = [
 ];
 /** Cross-phase contract marker (see header + packages/cli/src/commands/claude.ts). */
 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_…`.
+*/
+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`.
+*/
+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.
+*/
+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}.
+*/
+const PROXY_MODEL_ENV = {
+	ANTHROPIC_SMALL_FAST_MODEL: "claude-haiku-4-5",
+	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.
+*/
+const PROXY_AGENT_MODEL_ENV_VARS = ["ANTHROPIC_DEFAULT_SONNET_MODEL", "ANTHROPIC_DEFAULT_OPUS_MODEL"];
+/**
+* Inherited overrides that would send a proxy turn a model or header the proxy
+* can't price or doesn't expect. Dropped in proxy mode only.
+*/
+const PROXY_SCRUBBED_ENV_VARS = [
+	...[
+		...Object.keys(PROXY_MODEL_ENV),
+		...PROXY_AGENT_MODEL_ENV_VARS,
+		"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"
+	],
+	"ANTHROPIC_MODEL",
+	"ANTHROPIC_DEFAULT_FABLE_MODEL",
+	"ANTHROPIC_CUSTOM_HEADERS",
+	"CLAUDE_CODE_SUBAGENT_MODEL"
+];
 /** The single env var each credential kind is exported as. */
 const CREDENTIAL_ENV_VAR = {
 	oauth_token: "CLAUDE_CODE_OAUTH_TOKEN",
@@ -78,21 +145,30 @@ const CREDENTIAL_ENV_VAR = {
 * 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.
 */
-function buildChildEnv(base, extra, credential) {
+function buildChildEnv(base, extra, auth = { mode: "local_login" }) {
 	const merged = {
 		...base,
 		...extra
 	};
 	const scrubbed = new Set(SCRUBBED_ANTHROPIC_ENV_VARS);
-	if (credential) for (const key of PROVIDER_OVERRIDE_ENV_VARS) scrubbed.add(key);
+	if (auth.mode !== "local_login") for (const key of PROVIDER_OVERRIDE_ENV_VARS) scrubbed.add(key);
+	if (auth.mode === "ai_proxy") for (const key of PROXY_SCRUBBED_ENV_VARS) scrubbed.add(key);
 	const env = {};
 	for (const [key, value] of Object.entries(merged)) if (!scrubbed.has(key)) env[key] = value;
 	env[BRIDGE_ENV_VAR] = "1";
-	if (credential) env[CREDENTIAL_ENV_VAR[credential.kind]] = credential.value;
+	if (auth.mode === "credential") env[CREDENTIAL_ENV_VAR[auth.credential.kind]] = auth.credential.value;
+	else if (auth.mode === "ai_proxy") {
+		env.ANTHROPIC_BASE_URL = auth.baseUrl;
+		env.ANTHROPIC_AUTH_TOKEN = PROXY_API_KEY_PLACEHOLDER;
+		Object.assign(env, PROXY_MODEL_ENV);
+		for (const key of PROXY_AGENT_MODEL_ENV_VARS) env[key] = auth.model;
+		env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
+	}
 	return env;
 }
 //#endregion
@@ -173,14 +249,52 @@ function isAuthFailureText(text) {
 	const lower = text.toLowerCase();
 	return AUTH_FAILURE_MARKERS.some((marker) => lower.includes(marker));
 }
+/**
+* Proxy texts for a model this workspace or agent cannot use: 409
+* `model_route_denied` (unknown, disabled or mis-routed registry id) and 403
+* `model_not_approved` (tenant model policy). The 403 must not read as a
+* refused key.
+*/
+const MODEL_UNAVAILABLE_MARKERS = [
+	"model_route_denied",
+	"model_not_approved",
+	"model is not available",
+	"is restricted to:",
+	"not approved for this organization",
+	"requires an anthropic-routed model",
+	"no supported standard inference route",
+	"cannot use the standard data plane",
+	"not an enabled reviewed"
+];
+/**
+* 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.
+*/
+function classifyProxyDenial(text) {
+	const lower = text.toLowerCase();
+	if (lower.includes("no ai credits left") || lower.includes("partner account cannot run ai requests") || lower.includes("insufficient_credits") || lower.includes("credits_exhausted")) return "credits";
+	if (/\balfe (?:daily |weekly |monthly )?usage limit reached\b/.test(lower)) return "usage_limit";
+	if (MODEL_UNAVAILABLE_MARKERS.some((marker) => lower.includes(marker))) return "model_unavailable";
+	return null;
+}
 /** HTTP statuses on a `result` event that mean "credential refused". */
 function isAuthFailureStatus(status) {
 	return status === 401 || status === 403;
 }
 const AUTH_PROBE_TIMEOUT_MS = 6e4;
 const MAX_PROBE_OUTPUT_CHARS = 64e3;
-/** argv for the probe. No tools, no session file, no MCP, no settings files. */
-function buildProbeArgs() {
+/**
+* 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.
+*/
+function buildProbeArgs(model = "haiku") {
 	return [
 		"-p",
 		"--input-format",
@@ -188,7 +302,7 @@ function buildProbeArgs() {
 		"--output-format",
 		"json",
 		"--model",
-		"haiku",
+		model,
 		"--tools",
 		"",
 		"--system-prompt",
@@ -215,7 +329,15 @@ function parseProbeOutput(stdout, stderr, exitCode) {
 		if (record.type !== "result") continue;
 		if (record.is_error === false) return { result: "ok" };
 		const text = typeof record.result === "string" ? record.result : "";
-		if (isAuthFailureStatus(record.api_error_status) || isAuthFailureText(text)) return { result: "invalid" };
+		const denial = classifyProxyDenial(text);
+		if (denial) return {
+			result: "denied",
+			denial
+		};
+		if (isAuthFailureStatus(record.api_error_status) || isAuthFailureText(text)) return record.api_error_status === 403 ? {
+			result: "invalid",
+			forbidden: true
+		} : { result: "invalid" };
 		return {
 			result: "unknown",
 			reason: `probe failed (${typeof record.api_error_status === "number" ? `HTTP ${String(record.api_error_status)}` : "no auth error"})`
@@ -228,12 +350,14 @@ function parseProbeOutput(stdout, stderr, exitCode) {
 	};
 }
 /**
-* 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.
 */
 function runAuthProbe(opts) {
 	const spawnImpl = opts.spawnImpl ?? node_child_process.spawn;
-	const env = buildChildEnv(opts.baseEnv, { MAX_THINKING_TOKENS: "0" }, opts.credential);
+	const env = buildChildEnv(opts.baseEnv, { MAX_THINKING_TOKENS: "0" }, opts.auth);
+	const model = opts.auth.mode === "ai_proxy" ? PROXY_MODEL_ENV.ANTHROPIC_DEFAULT_HAIKU_MODEL : void 0;
 	return new Promise((resolve) => {
 		if (opts.signal?.aborted) {
 			resolve({
@@ -266,7 +390,7 @@ function runAuthProbe(opts) {
 		}
 		let child;
 		try {
-			child = spawnImpl(opts.claudeBin ?? "claude", buildProbeArgs(), {
+			child = spawnImpl(opts.claudeBin ?? "claude", buildProbeArgs(model), {
 				cwd: opts.cwd,
 				env,
 				stdio: [
@@ -338,6 +462,7 @@ var CredentialStatusReporter = class {
 	async deliver(report) {
 		const key = JSON.stringify([
 			report.status,
+			report.source ?? null,
 			report.revision ?? null,
 			report.detail ?? null
 		]);
@@ -353,6 +478,64 @@ var CredentialStatusReporter = class {
 	}
 };
 //#endregion
+//#region src/mcp-allow-rules.ts
+/**
+* Allow rules for the MCP servers a bridged turn loads.
+*
+* Turns run under `--permission-mode dontAsk`, which DENIES any tool not in
+* `--allowedTools`. MCP tools are named `mcp__<server>__<tool>`, so without a
+* rule per server every MCP call (alfe-platform memory/voice/send/secrets and
+* every integration server) is refused (prod, 2026-10-17). Turns pass
+* `--strict-mcp-config --mcp-config <file>`, so the servers in that file are
+* exactly the Alfe-installed set; each gets a server-wide `mcp__<server>` rule.
+* No blanket `mcp__*` wildcard: the allow-list stays scoped to what Alfe wrote.
+*
+* The file is read on every spawn, so a newly installed integration server is
+* allowed on the next turn without restarting the host.
+*/
+const CLAUDE_AI_PREFIX = "claude.ai ";
+/**
+* Mirrors how claude (2.1.x) builds the `<server>` segment of an MCP tool id:
+* every character outside `[a-zA-Z0-9_-]` becomes `_` (hyphens are kept), and
+* `claude.ai ` connector names also collapse and trim underscores. Permission
+* rules match on this normalised name, so a rule must use it too.
+*/
+function normalizeMcpServerName(name) {
+	let normalized = name.replace(/[^a-zA-Z0-9_-]/g, "_");
+	if (name.startsWith(CLAUDE_AI_PREFIX)) normalized = normalized.replace(/_+/g, "_").replace(/^_|_$/g, "");
+	return normalized;
+}
+/**
+* Server-wide allow rules (`mcp__<server>`) for every server in the
+* `--mcp-config` file. A missing or malformed file yields no rules and one
+* warning; the turn still runs, it just cannot call MCP tools.
+*/
+function mcpServerAllowRules(configPath, log) {
+	if (!configPath) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse((0, node_fs.readFileSync)(configPath, "utf8"));
+	} catch (err) {
+		log.warn(`[claude-host] could not read MCP config ${configPath}; MCP tools are not allowed this turn: ${err instanceof Error ? err.message : String(err)}`);
+		return [];
+	}
+	const servers = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.mcpServers : void 0;
+	if (servers === null || typeof servers !== "object" || Array.isArray(servers)) {
+		log.warn(`[claude-host] MCP config ${configPath} has no mcpServers map; MCP tools are not allowed this turn`);
+		return [];
+	}
+	const rules = /* @__PURE__ */ new Set();
+	for (const name of Object.keys(servers)) {
+		const normalized = normalizeMcpServerName(name);
+		if (!normalized || normalized.includes("__")) {
+			log.warn(`[claude-host] MCP server "${name}" cannot be expressed as a server-wide allow rule; its tools stay denied`);
+			continue;
+		}
+		rules.add(`mcp__${normalized}`);
+	}
+	return [...rules];
+}
+//#endregion
 //#region src/stream-mapper.ts
 /**
 * Claude Code `--output-format stream-json` → Alfe chat-activity mapper.
@@ -600,7 +783,8 @@ function mapStreamEvent(state, raw, nowMs) {
 			finalText: isError ? "" : finalText,
 			...durationMs !== void 0 ? { durationMs } : {},
 			...errorMessage ? { errorMessage } : {},
-			...authFailed ? { authFailed: true } : {}
+			...authFailed ? { authFailed: true } : {},
+			...authFailed && evt.api_error_status === 403 ? { authForbidden: true } : {}
 		}];
 	}
 	return [];
@@ -811,7 +995,7 @@ var SessionDriver = class {
 	abortCurrent = null;
 	bin;
 	baseEnv;
-	credential;
+	auth;
 	managed;
 	log;
 	/** Injected spawn — tests replace this with a fake child. */
@@ -819,7 +1003,7 @@ var SessionDriver = class {
 	constructor(opts) {
 		this.bin = opts?.claudeBin ?? DEFAULT_CLAUDE_BIN;
 		this.baseEnv = opts?.baseEnv ?? process.env;
-		this.credential = opts?.credential ?? null;
+		this.auth = opts?.auth ?? { mode: "local_login" };
 		this.managed = opts?.managed ?? false;
 		this.log = opts?.logger ?? console;
 		this.spawnImpl = opts?.__spawn ?? node_child_process.spawn;
@@ -844,7 +1028,7 @@ var SessionDriver = class {
 		return this.runPerTurn(params);
 	}
 	buildArgs(params) {
-		const allowed = (params.allowedTools ?? (this.managed ? MANAGED_ALLOWED_TOOLS : DEFAULT_ALLOWED_TOOLS)).join(",");
+		const allowed = [...params.allowedTools ?? (this.managed ? MANAGED_ALLOWED_TOOLS : DEFAULT_ALLOWED_TOOLS), ...mcpServerAllowRules(params.mcpConfigPath, this.log)].join(",");
 		const permissionMode = params.permissionMode ?? "dontAsk";
 		if (!CLAUDE_PERMISSION_MODES.includes(permissionMode)) throw new Error(`Unsupported Claude permission mode: ${permissionMode}`);
 		const args = [
@@ -879,7 +1063,7 @@ var SessionDriver = class {
 		let stderr = "";
 		let rateLimited = false;
 		const args = this.buildArgs(params);
-		const env = buildChildEnv(this.baseEnv, void 0, this.credential);
+		const env = buildChildEnv(this.baseEnv, void 0, this.auth);
 		return new Promise((resolve) => {
 			let child;
 			try {
@@ -931,7 +1115,8 @@ var SessionDriver = class {
 					finalText: finalIsError ? "" : endText,
 					...finalErrMsg ? { errorMessage: finalErrMsg } : {},
 					aborted,
-					...authFailed ? { authFailed: true } : {}
+					...authFailed ? { authFailed: true } : {},
+					...authFailed && end?.type === "turn-end" && end.authForbidden ? { authForbidden: true } : {}
 				});
 			};
 			const requestTermination = (reason) => {
@@ -1059,6 +1244,27 @@ async function writeTextAtomically(path, contents) {
 *
 * where `sessionId = conversationId ?? sessionKey`.
 */
+/**
+* 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.
+*/
+const CHAT_SESSION_CHANNEL = "alfe";
+/**
+* Values hosts up to 0.1.16 stored as `channel`: the chat surface label
+* (`params.clientType ?? 'chat'`). Read as `CHAT_SESSION_CHANNEL`; the file is
+* rewritten on its next save.
+*/
+const LEGACY_SURFACE_CHANNELS = new Set([
+	"chat",
+	"dashboard",
+	"mobile",
+	"desktop",
+	"widget",
+	"unknown"
+]);
+/** Legacy values that never named a real surface, so carry no `clientType`. */
+const LEGACY_PLACEHOLDER_CHANNELS = new Set(["chat", "unknown"]);
 function sessionsDir() {
 	return process.env.ALFE_SESSIONS_DIR ?? (0, node_path.join)((0, node_os.homedir)(), ".alfe", "sessions", "chat");
 }
@@ -1077,6 +1283,7 @@ function sessionPath(sessionId) {
 function asSessionData(value, expectedSessionId) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
 	const record = value;
+	normaliseLegacyChannel(record);
 	if (typeof record.sessionId !== "string" || expectedSessionId !== void 0 && record.sessionId !== expectedSessionId || typeof record.agentId !== "string" || typeof record.channel !== "string" || typeof record.createdAt !== "string" || typeof record.updatedAt !== "string" || !Array.isArray(record.messages)) return null;
 	if (!record.messages.every((message) => {
 		if (!message || typeof message !== "object" || Array.isArray(message)) return false;
@@ -1087,6 +1294,13 @@ function asSessionData(value, expectedSessionId) {
 	if (record.memory !== void 0 && !isMemoryCursor(record.memory)) delete record.memory;
 	return value;
 }
+/** Map a pre-0.1.17 surface-label channel (or none) onto `CHAT_SESSION_CHANNEL`. */
+function normaliseLegacyChannel(record) {
+	const channel = record.channel;
+	if (channel !== void 0 && !(typeof channel === "string" && LEGACY_SURFACE_CHANNELS.has(channel))) return;
+	if (typeof channel === "string" && !LEGACY_PLACEHOLDER_CHANNELS.has(channel) && record.clientType === void 0) record.clientType = channel;
+	record.channel = CHAT_SESSION_CHANNEL;
+}
 function isMemoryCursor(value) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
 	const cursor = value;
@@ -1141,12 +1355,13 @@ async function saveSession(session) {
 	session.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
 	await writeTextAtomically(sessionPath(session.sessionId), JSON.stringify(session, null, 2));
 }
-async function createSession(sessionId, agentId, channel, tenantId, userId) {
+async function createSession(sessionId, agentId, channel, tenantId, userId, clientType) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	const session = {
 		sessionId,
 		agentId,
 		channel,
+		...clientType ? { clientType } : {},
 		tenantId,
 		userId,
 		createdAt: now,
@@ -1180,17 +1395,35 @@ async function withSessionLock(sessionId, fn) {
 * memory-ingest index, or -1 when the session does not exist.
 */
 async function addMessage(sessionId, role, content, senderId, senderName, components, attachments) {
+	return appendMessage(sessionId, {
+		role,
+		content,
+		...senderId ? { senderId } : {},
+		...senderName ? { senderName } : {},
+		...components?.length ? { components } : {},
+		...attachments?.length ? { attachments } : {}
+	});
+}
+/**
+* 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.
+*/
+async function addErrorMessage(sessionId, content) {
+	return appendMessage(sessionId, {
+		role: "assistant",
+		content,
+		kind: "error"
+	});
+}
+async function appendMessage(sessionId, message) {
 	return withSessionLock(sessionId, async () => {
 		const session = await getSession(sessionId);
 		if (!session) return -1;
+		const last = session.messages.at(-1)?.timestamp ?? 0;
 		session.messages.push({
-			role,
-			content,
-			timestamp: Date.now(),
-			...senderId ? { senderId } : {},
-			...senderName ? { senderName } : {},
-			...components?.length ? { components } : {},
-			...attachments?.length ? { attachments } : {}
+			...message,
+			timestamp: Math.max(Date.now(), last + 1)
 		});
 		await saveSession(session);
 		return session.messages.length - 1;
@@ -1278,8 +1511,8 @@ async function ensureMemoryCursor(sessionId) {
 /**
 * The messages not yet accepted by the memory service, oldest first, bounded
 * by count and serialised bytes (always at least one message when any is
-* pending). Whitespace-only messages are skipped (the service rejects empty
-* content) but still covered: `throughIndex` is the last index this batch
+* pending). Error replies (history only) and whitespace-only messages (the
+* service rejects empty content) are skipped but still covered: `throughIndex` is the last index this batch
 * accounts for, sent or skipped. Leftovers go out with the next turn's batch.
 */
 async function pendingMemoryBatch(sessionId, opts = {}) {
@@ -1297,7 +1530,7 @@ async function pendingMemoryBatch(sessionId, opts = {}) {
 		let bytes = 0;
 		for (let index = session.memory.lastIngestedIndex + 1; index < session.messages.length && messages.length < maxMessages; index += 1) {
 			const message = session.messages[index];
-			if (message.content.trim() === "") {
+			if (message.kind === "error" || message.content.trim() === "") {
 				throughIndex = index;
 				continue;
 			}
@@ -1585,14 +1818,15 @@ const RECALL_TIMEOUT_MS = 5e3;
 //#endregion
 //#region src/host.ts
 /**
-* ClaudeCodeHost — the persistent chat bridge for a self-hosted Claude Code
-* agent.
+* ClaudeCodeHost — the persistent chat bridge for a Claude Code agent
+* (self-hosted or managed).
 *
 * It holds ONE `ChatServiceClient` (reused verbatim from `@alfe.ai/chat`, with
 * NO custom reconnect — the client already backs off with jitter and guards
 * against orphan sockets), registers the inbound RPC handlers the chat service
-* calls, and drives the `SessionDriver` to run `claude -p` turns on the user's
-* subscription.
+* calls, and drives the `SessionDriver` to run `claude -p` turns on one auth
+* source: the agent's stored credential, a self-hosted machine's own login, or
+* the Alfe AI proxy (see DEVELOPING.md "Auth source resolution").
 *
 * Every wire shape here is byte-for-byte the shape the `@alfe.ai/openclaw-chat`
 * plugin emits, so the chat service / adapter / UI treat a Claude Code turn
@@ -1630,9 +1864,28 @@ const PERSONA_POINTER_SYSTEM_PROMPT = [
 	"Fully embody that persona in how you speak and act; respond AS that agent, not as a generic coding assistant."
 ].join("\n");
 const CREDENTIAL_INVALID_MESSAGE = "This agent's Claude credential is invalid or expired. Update it in agent settings.";
-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.";
-const CREDENTIAL_MISSING_MESSAGE = "This agent has no Claude credential. Add a Claude subscription token or an Anthropic API key in agent settings.";
+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.";
+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.";
+const LOCAL_LOGIN_SWITCHED_MESSAGE = "Your machine's Claude login stopped working, so this agent switched to Alfe credits. Please resend your message.";
+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.";
+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.";
+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.";
 const CREDENTIAL_UNAVAILABLE_MESSAGE = "This agent's Claude credential couldn't be loaded yet. Try again in a moment.";
+/** Fixed status details (never `claude` output). */
+const SOURCE_OK_DETAIL = {
+	local_login: "Using this machine's claude login",
+	ai_proxy: "Using Alfe AI credits"
+};
+const DENIAL_DETAIL = {
+	credits: "Using Alfe AI credits. This workspace is out of credits.",
+	usage_limit: "Using Alfe AI credits. An Alfe usage limit has been reached.",
+	model_unavailable: "Using Alfe AI credits. The agent's model is not available on this workspace."
+};
+const DENIAL_MESSAGE = {
+	credits: OUT_OF_CREDITS_MESSAGE,
+	usage_limit: USAGE_LIMIT_MESSAGE,
+	model_unavailable: MODEL_UNAVAILABLE_MESSAGE
+};
 const MAX_AGENT_MESSAGE_BYTES = 256 * 1024;
 const MAX_SESSION_KEY_CHARS = 768;
 const MAX_IDENTIFIER_CHARS = 512;
@@ -1856,8 +2109,16 @@ var ClaudeCodeHost = class {
 	/** Turns waiting for the credential, before queue admission (chat.abort). */
 	waitingTurns = /* @__PURE__ */ new Map();
 	loaderRestartMs;
+	/** How often a fallen-back self-hosted agent re-checks its local login. */
+	localLoginRecheckMs;
+	localLoginRecheck = null;
 	/** In memory only. Never logged, never persisted. */
 	credential = null;
+	/**
+	* The auth every new turn runs on, resolved once the credential fetch
+	* answers (see `resolveAuthSource`). Null before that.
+	*/
+	authSource = null;
 	credentialAbort = new AbortController();
 	reporter;
 	probe;
@@ -1867,18 +2128,18 @@ var ClaudeCodeHost = class {
 		this.cfg = cfg;
 		this.log = cfg.logger ?? console;
 		this.claudeSessionsPath = cfg.claudeSessionsPath ?? (0, node_path.join)((0, node_os.homedir)(), ".alfe", "claude-code", "sessions.json");
-		this.makeDriver = deps?.makeDriver ?? ((credential) => new SessionDriver({
+		this.makeDriver = deps?.makeDriver ?? ((auth) => new SessionDriver({
 			logger: this.log,
 			baseEnv: process.env,
-			credential,
+			auth,
 			managed: cfg.managed === true
 		}));
 		this.api = deps?.api ?? new _alfe_ai_agent_api_client.AgentApiClient({
 			apiKey: cfg.apiKey,
 			apiUrl: cfg.apiUrl
 		});
-		this.probe = deps?.probe ?? ((credential, signal) => runAuthProbe({
-			credential,
+		this.probe = deps?.probe ?? ((auth, signal) => runAuthProbe({
+			auth,
 			baseEnv: process.env,
 			cwd: (0, node_os.tmpdir)(),
 			signal
@@ -1886,6 +2147,7 @@ var ClaudeCodeHost = class {
 		this.credentialWaitMs = deps?.credentialWaitMs ?? 15e3;
 		this.loaderRestartMs = deps?.loaderRestartMs ?? 5e3;
 		this.credentialRetry = deps?.credentialRetry ?? {};
+		this.localLoginRecheckMs = deps?.localLoginRecheckMs ?? 9e5;
 		this.reporter = new CredentialStatusReporter((report) => this.api.reportClaudeCredentialStatus(report), { log: this.log });
 		this.chat = deps?.chat ?? new _alfe_ai_chat.ChatServiceClient({
 			wsUrl: cfg.wsUrl,
@@ -1939,49 +2201,117 @@ var ClaudeCodeHost = class {
 		});
 		if (!loaded) return;
 		this.credential = loaded.credential;
+		this.authSource = loaded.credential ? "credential" : this.cfg.managed ? "ai_proxy" : "local_login";
 		this.credentialLoaded = true;
 		this.resolveCredentialReady();
 		await this.checkCredential();
 	}
-	childCredential() {
-		return this.credential ? {
-			kind: this.credential.kind,
-			value: this.credential.value
-		} : null;
+	/**
+	* A method, not a property read: `stopping` flips across awaits, which
+	* control-flow narrowing cannot see.
+	*/
+	isStopping() {
+		return this.stopping;
+	}
+	/** Same reason as `isStopping`: `authSource` can change across an await. */
+	currentAuthSource() {
+		return this.authSource;
+	}
+	/** The auth a new turn runs on. Local login until the fetch has answered. */
+	childAuth() {
+		if (this.authSource === "credential" && this.credential) return {
+			mode: "credential",
+			credential: {
+				kind: this.credential.kind,
+				value: this.credential.value
+			}
+		};
+		if (this.authSource === "ai_proxy") return {
+			mode: "ai_proxy",
+			baseUrl: this.cfg.localAiProxyUrl ?? "http://127.0.0.1:18193",
+			model: this.cfg.model ?? "claude-haiku-4-5"
+		};
+		return { mode: "local_login" };
 	}
-	/** Start-up health check: one minimal real call, reported to the cloud. */
-	async checkCredential() {
-		if (!this.credential && this.cfg.managed) {
-			await this.reporter.report({
-				status: "missing",
-				detail: "No Claude credential is stored for this agent"
-			});
+	/**
+	* 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.
+	*/
+	fallBackToProxy(why) {
+		if (this.authSource !== "local_login") return;
+		this.log.warn(`[claude-host] the claude login on this machine was refused (${why}); using the Alfe AI proxy`);
+		this.authSource = "ai_proxy";
+		this.scheduleLocalLoginRecheck();
+	}
+	scheduleLocalLoginRecheck() {
+		if (this.localLoginRecheck || this.stopping) return;
+		this.localLoginRecheck = setTimeout(() => {
+			this.localLoginRecheck = null;
+			this.recheckLocalLogin();
+		}, this.localLoginRecheckMs);
+		this.localLoginRecheck.unref();
+	}
+	/** While fallen back: one local-login probe; back to the login when it works. */
+	async recheckLocalLogin() {
+		if (this.isStopping() || this.authSource !== "ai_proxy" || this.credential || this.cfg.managed) return;
+		let outcome;
+		try {
+			outcome = await this.probe({ mode: "local_login" }, this.credentialAbort.signal);
+		} catch (err) {
+			outcome = {
+				result: "unknown",
+				reason: err instanceof Error ? err.message : String(err)
+			};
+		}
+		if (this.isStopping() || this.currentAuthSource() !== "ai_proxy") return;
+		if (outcome.result === "ok") {
+			this.log.info("[claude-host] the claude login on this machine works again; leaving the Alfe AI proxy");
+			this.authSource = "local_login";
+			await this.reportStatus("ok");
 			return;
 		}
-		const outcome = await this.probe(this.childCredential(), this.credentialAbort.signal);
+		this.scheduleLocalLoginRecheck();
+	}
+	/**
+	* 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.
+	*/
+	async checkCredential() {
+		let outcome = await this.probe(this.childAuth(), this.credentialAbort.signal);
 		if (this.stopping) return;
-		if (outcome.result === "unknown") {
-			this.log.warn(`[claude-host] Claude auth check inconclusive (${outcome.reason}); the next turn will tell`);
-			return;
+		if (outcome.result === "invalid" && !outcome.forbidden && this.authSource === "local_login") {
+			this.fallBackToProxy("start-up check");
+			outcome = await this.probe(this.childAuth(), this.credentialAbort.signal);
+			if (this.isStopping()) return;
 		}
-		await this.reportAuth(outcome.result === "ok");
-	}
-	/** Report the credential (or the local login) as working or refused. */
-	async reportAuth(ok) {
-		if (!this.credentialLoaded) return;
-		const revision = this.credential?.revision;
-		if (ok) await this.reporter.report({
-			status: "ok",
-			...revision ? { revision } : { detail: "Using this machine's claude login" }
-		});
-		else if (revision) await this.reporter.report({
-			status: "invalid",
-			detail: "Anthropic rejected the stored credential",
-			revision
-		});
-		else await this.reporter.report({
-			status: "missing",
-			detail: "No Claude credential, and the claude login on this machine is not signed in"
+		switch (outcome.result) {
+			case "unknown":
+				this.log.warn(`[claude-host] Claude auth check inconclusive (${outcome.reason}); the next turn will tell`);
+				return;
+			case "denied":
+				if (outcome.denial === "model_unavailable") {
+					this.log.warn("[claude-host] the probe model is unavailable through the Alfe AI proxy; the next turn will tell");
+					return;
+				}
+				await this.reportStatus("ok", DENIAL_DETAIL[outcome.denial]);
+				return;
+			default: await this.reportStatus(outcome.result);
+		}
+	}
+	/** Report the current auth source as working or refused. */
+	async reportStatus(status, detail) {
+		const source = this.authSource;
+		if (!this.credentialLoaded || !source) return;
+		const revision = source === "credential" ? this.credential?.revision : void 0;
+		const fixedDetail = detail ?? (status === "ok" ? source === "credential" ? void 0 : SOURCE_OK_DETAIL[source] : source === "credential" ? "Anthropic rejected the stored credential" : source === "ai_proxy" ? "The Alfe AI proxy rejected this agent's key" : "The claude login on this machine is not signed in");
+		await this.reporter.report({
+			status,
+			source,
+			...fixedDetail ? { detail: fixedDetail } : {},
+			...revision ? { revision } : {}
 		});
 	}
 	/**
@@ -2025,7 +2355,6 @@ var ClaudeCodeHost = class {
 	credentialGateMessage() {
 		if (!this.credentialReady) return null;
 		if (!this.credentialLoaded) return CREDENTIAL_UNAVAILABLE_MESSAGE;
-		if (!this.credential && this.cfg.managed) return CREDENTIAL_MISSING_MESSAGE;
 		return null;
 	}
 	/** Stop admission, abort owned children, and give active turns time to settle. */
@@ -2033,6 +2362,10 @@ var ClaudeCodeHost = class {
 		if (this.stopPromise) return this.stopPromise;
 		this.stopping = true;
 		this.credentialAbort.abort();
+		if (this.localLoginRecheck) {
+			clearTimeout(this.localLoginRecheck);
+			this.localLoginRecheck = null;
+		}
 		for (const waiting of this.waitingTurns.values()) for (const turn of waiting) turn.cancellation.abort();
 		this.queues.stop();
 		for (const { driver, cancellation } of this.runningTurns.values()) {
@@ -2182,10 +2515,7 @@ var ClaudeCodeHost = class {
 		await addMessage(bareSessionId, "user", params.message, params.identityId ?? params.userId, params.displayName);
 		const credentialProblem = this.credentialGateMessage();
 		if (credentialProblem) {
-			complete({
-				ok: false,
-				payload: { message: credentialProblem }
-			});
+			await this.failTurn(bareSessionId, complete, credentialProblem);
 			return;
 		}
 		let memoryContext = "";
@@ -2200,26 +2530,36 @@ var ClaudeCodeHost = class {
 		const mcpConfigPath = this.cfg.mcpConfigPath && (0, node_fs.existsSync)(this.cfg.mcpConfigPath) ? this.cfg.mcpConfigPath : void 0;
 		const appendSystemPrompt = this.buildSystemPrompt(memoryContext, isVoice);
 		const claudeSessionId = this.claudeSessionIds.get(bareSessionId) ?? null;
-		const driver = this.makeDriver(this.childCredential());
 		const cancellation = new AbortController();
-		this.runningTurns.set(sessionKey, {
-			runId,
-			driver,
-			cancellation
-		});
+		let auth = this.childAuth();
+		let switchedWithoutRerun = false;
 		let result;
 		try {
-			result = await this.runWithResumeFallback(driver, bareSessionId, cancellation.signal, {
+			result = await this.runTurnOn(auth, sessionKey, runId, cancellation, bareSessionId, {
 				prompt: params.message,
 				claudeSessionId,
 				cwd: this.cfg.workspace,
 				...mcpConfigPath ? { mcpConfigPath } : {},
 				...appendSystemPrompt ? { appendSystemPrompt } : {},
-				...this.cfg.model ? { model: this.cfg.model } : {},
 				onEmission: (emission) => {
 					this.forwardEmission(runId, sessionKey, emission);
 				}
 			}, isVoice);
+			if (auth.mode === "local_login" && result.isError && result.authFailed && !result.authForbidden && !result.aborted && !cancellation.signal.aborted && !this.isStopping()) {
+				this.fallBackToProxy("turn refused");
+				if (producedVisibleOutput(result.emissions)) switchedWithoutRerun = true;
+				else auth = this.childAuth();
+				if (!switchedWithoutRerun && auth.mode === "ai_proxy") result = await this.runTurnOn(auth, sessionKey, runId, cancellation, bareSessionId, {
+					prompt: params.message,
+					claudeSessionId,
+					cwd: this.cfg.workspace,
+					...mcpConfigPath ? { mcpConfigPath } : {},
+					...appendSystemPrompt ? { appendSystemPrompt } : {},
+					onEmission: (emission) => {
+						this.forwardEmission(runId, sessionKey, emission);
+					}
+				}, isVoice);
+			}
 		} finally {
 			this.runningTurns.delete(sessionKey);
 		}
@@ -2237,21 +2577,30 @@ var ClaudeCodeHost = class {
 			return;
 		}
 		if (result.isError) {
+			const denial = auth.mode === "ai_proxy" ? classifyProxyDenial(result.errorMessage ?? "") : null;
+			if (denial) {
+				await this.failTurn(bareSessionId, complete, DENIAL_MESSAGE[denial]);
+				await this.reportStatus("ok", DENIAL_DETAIL[denial]);
+				return;
+			}
+			if (switchedWithoutRerun) {
+				await this.failTurn(bareSessionId, complete, LOCAL_LOGIN_SWITCHED_MESSAGE);
+				return;
+			}
+			if (result.authFailed && auth.mode === "local_login") {
+				await this.failTurn(bareSessionId, complete, result.authForbidden ? LOCAL_LOGIN_REFUSED_MESSAGE : CREDENTIAL_INVALID_MESSAGE);
+				await this.reportStatus("invalid");
+				return;
+			}
 			if (result.authFailed) {
-				complete({
-					ok: false,
-					payload: { message: this.credential ? CREDENTIAL_INVALID_MESSAGE : LOCAL_LOGIN_FAILED_MESSAGE }
-				});
-				await this.reportAuth(false);
+				await this.failTurn(bareSessionId, complete, auth.mode === "ai_proxy" ? PROXY_AUTH_FAILED_MESSAGE : CREDENTIAL_INVALID_MESSAGE);
+				await this.reportStatus("invalid");
 				return;
 			}
-			complete({
-				ok: false,
-				payload: { message: result.errorMessage ?? "Claude Code turn failed" }
-			});
+			await this.failTurn(bareSessionId, complete, result.errorMessage ?? "Claude Code turn failed");
 			return;
 		}
-		this.reportAuth(true);
+		this.reportStatus("ok");
 		if (result.finalText) await addMessage(bareSessionId, "assistant", result.finalText);
 		const notification = result.finalText ? {
 			conversationId: bareSessionId,
@@ -2267,6 +2616,23 @@ var ClaudeCodeHost = class {
 		await this.ingestPendingMemory(bareSessionId, params);
 	}
 	/**
+	* 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.
+	*/
+	async failTurn(bareSessionId, complete, message) {
+		try {
+			await addErrorMessage(bareSessionId, message);
+		} catch (err) {
+			this.log.warn(`[claude-host] failed to store a turn error in history: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		complete({
+			ok: false,
+			payload: { message }
+		});
+	}
+	/**
 	* Send every message the memory service has not accepted yet. Indices are
 	* the messages' positions in the session file, so they advance across turns
 	* and survive host restarts; the per-conversation `ingestEpoch` tells the
@@ -2324,6 +2690,24 @@ var ClaudeCodeHost = class {
 	* 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.
+	*/
+	runTurnOn(auth, sessionKey, runId, cancellation, bareSessionId, baseParams, isVoice) {
+		const driver = this.makeDriver(auth);
+		this.runningTurns.set(sessionKey, {
+			runId,
+			driver,
+			cancellation
+		});
+		const model = auth.mode === "ai_proxy" ? auth.model : this.cfg.model;
+		return this.runWithResumeFallback(driver, bareSessionId, cancellation.signal, {
+			...baseParams,
+			...model ? { model } : {}
+		}, isVoice);
+	}
 	async runWithResumeFallback(driver, bareSessionId, cancellation, baseParams, isVoice) {
 		const cancelled = () => cancellation.aborted || this.stopping;
 		const aborted = (result) => ({
@@ -2449,7 +2833,7 @@ var ClaudeCodeHost = class {
 	async buildHistoryPreamble(bareSessionId) {
 		const session = await getSession(bareSessionId);
 		if (!session || session.messages.length === 0) return "";
-		const prior = session.messages.slice(0, -1).slice(-10);
+		const prior = session.messages.slice(0, -1).filter((m) => m.kind !== "error").slice(-10);
 		if (prior.length === 0) return "";
 		return `Earlier in this conversation:\n${prior.map((m) => `${m.role === "assistant" ? "Assistant" : "User"}: ${m.content}`).join("\n")}`;
 	}
@@ -2459,7 +2843,7 @@ var ClaudeCodeHost = class {
 			if (params.tenantId && existing.tenantId && params.tenantId !== existing.tenantId || params.userId && existing.userId && params.userId !== existing.userId) throw new Error("Session ownership metadata mismatch");
 			return;
 		}
-		await createSession(bareSessionId, params.agentId, params.clientType ?? "chat", params.tenantId, params.userId);
+		await createSession(bareSessionId, params.agentId, CHAT_SESSION_CHANNEL, params.tenantId, params.userId, params.clientType);
 	}
 	async loadClaudeSessionIds() {
 		try {
@@ -2535,6 +2919,13 @@ function stripAgentPrefix(sessionKey) {
 	if (parts.length >= 3 && parts[0] === "agent") return parts.slice(2).join(":");
 	return sessionKey;
 }
+/**
+* True when a turn already showed the user something (text or any activity
+* card). A refused turn that did is never re-run: its tools may have run.
+*/
+function producedVisibleOutput(emissions) {
+	return emissions.some((emission) => emission.type === "chat-activity" || emission.type === "chat-delta" && emission.text.trim().length > 0);
+}
 //#endregion
 //#region src/host-config.ts
 /**
@@ -2556,6 +2947,7 @@ function buildHostConfig(resolved, home, chat, env) {
 	if (!chat.apiKey || !chat.chatWsUrl) throw new Error("Unable to resolve chat service URL / API key from ~/.alfe/config.toml. Run `alfe login`.");
 	const model = env.ALFE_DEFAULT_MODEL?.trim();
 	const managedFlag = env.ALFE_MANAGED?.trim().toLowerCase();
+	const localAiProxyUrl = parseLoopbackUrl(env.ALFE_LOCAL_AI_PROXY_URL);
 	return {
 		wsUrl: chat.chatWsUrl,
 		apiKey: chat.apiKey,
@@ -2564,10 +2956,30 @@ function buildHostConfig(resolved, home, chat, env) {
 		mcpConfigPath: (0, node_path.join)(home, "mcp-config.json"),
 		claudeSessionsPath: (0, node_path.join)((0, node_os.homedir)(), ".alfe", "claude-code", "sessions.json"),
 		...model ? { model } : {},
-		managed: managedFlag === "1" || managedFlag === "true"
+		managed: managedFlag === "1" || managedFlag === "true",
+		...localAiProxyUrl ? { localAiProxyUrl } : {}
 	};
 }
 /**
+* The daemon's loopback AI proxy URL (`ALFE_LOCAL_AI_PROXY_URL`), as a bare
+* origin. Only plain-http loopback is accepted: the proxy-mode `claude` child
+* sends every model request there, so a stray value must never point it off
+* the machine. Anything else → undefined (the host default applies).
+*/
+function parseLoopbackUrl(raw) {
+	const value = raw?.trim();
+	if (!value) return void 0;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		return;
+	}
+	if (url.protocol !== "http:") return void 0;
+	if (url.hostname !== "127.0.0.1" && url.hostname !== "localhost") return void 0;
+	return url.origin;
+}
+/**
 * Build the host config. Throws (→ non-zero exit from the CLI) when the chat
 * URL / api key can't resolve.
 */
@@ -2606,12 +3018,6 @@ Object.defineProperty(exports, "CREDENTIAL_INVALID_MESSAGE", {
 		return CREDENTIAL_INVALID_MESSAGE;
 	}
 });
-Object.defineProperty(exports, "CREDENTIAL_MISSING_MESSAGE", {
-	enumerable: true,
-	get: function() {
-		return CREDENTIAL_MISSING_MESSAGE;
-	}
-});
 Object.defineProperty(exports, "CREDENTIAL_UNAVAILABLE_MESSAGE", {
 	enumerable: true,
 	get: function() {
@@ -2636,16 +3042,28 @@ Object.defineProperty(exports, "DEFAULT_ALLOWED_TOOLS", {
 		return DEFAULT_ALLOWED_TOOLS;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_LOCAL_AI_PROXY_URL", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_LOCAL_AI_PROXY_URL;
+	}
+});
 Object.defineProperty(exports, "DEFAULT_PERMISSION_MODE", {
 	enumerable: true,
 	get: function() {
 		return DEFAULT_PERMISSION_MODE;
 	}
 });
-Object.defineProperty(exports, "LOCAL_LOGIN_FAILED_MESSAGE", {
+Object.defineProperty(exports, "LOCAL_LOGIN_REFUSED_MESSAGE", {
 	enumerable: true,
 	get: function() {
-		return LOCAL_LOGIN_FAILED_MESSAGE;
+		return LOCAL_LOGIN_REFUSED_MESSAGE;
+	}
+});
+Object.defineProperty(exports, "LOCAL_LOGIN_SWITCHED_MESSAGE", {
+	enumerable: true,
+	get: function() {
+		return LOCAL_LOGIN_SWITCHED_MESSAGE;
 	}
 });
 Object.defineProperty(exports, "MANAGED_ALLOWED_TOOLS", {
@@ -2660,6 +3078,48 @@ Object.defineProperty(exports, "MANAGED_DISALLOWED_TOOLS", {
 		return MANAGED_DISALLOWED_TOOLS;
 	}
 });
+Object.defineProperty(exports, "MODEL_UNAVAILABLE_MESSAGE", {
+	enumerable: true,
+	get: function() {
+		return MODEL_UNAVAILABLE_MESSAGE;
+	}
+});
+Object.defineProperty(exports, "OUT_OF_CREDITS_MESSAGE", {
+	enumerable: true,
+	get: function() {
+		return OUT_OF_CREDITS_MESSAGE;
+	}
+});
+Object.defineProperty(exports, "PROXY_AGENT_MODEL_ENV_VARS", {
+	enumerable: true,
+	get: function() {
+		return PROXY_AGENT_MODEL_ENV_VARS;
+	}
+});
+Object.defineProperty(exports, "PROXY_API_KEY_PLACEHOLDER", {
+	enumerable: true,
+	get: function() {
+		return PROXY_API_KEY_PLACEHOLDER;
+	}
+});
+Object.defineProperty(exports, "PROXY_AUTH_FAILED_MESSAGE", {
+	enumerable: true,
+	get: function() {
+		return PROXY_AUTH_FAILED_MESSAGE;
+	}
+});
+Object.defineProperty(exports, "PROXY_DEFAULT_MODEL", {
+	enumerable: true,
+	get: function() {
+		return PROXY_DEFAULT_MODEL;
+	}
+});
+Object.defineProperty(exports, "PROXY_MODEL_ENV", {
+	enumerable: true,
+	get: function() {
+		return PROXY_MODEL_ENV;
+	}
+});
 Object.defineProperty(exports, "SCRUBBED_ANTHROPIC_ENV_VARS", {
 	enumerable: true,
 	get: function() {
@@ -2690,6 +3150,12 @@ Object.defineProperty(exports, "TURN_TIMEOUT_MS", {
 		return TURN_TIMEOUT_MS;
 	}
 });
+Object.defineProperty(exports, "USAGE_LIMIT_MESSAGE", {
+	enumerable: true,
+	get: function() {
+		return USAGE_LIMIT_MESSAGE;
+	}
+});
 Object.defineProperty(exports, "WARM_STREAMING_SUPPORTED", {
 	enumerable: true,
 	get: function() {
@@ -2720,6 +3186,12 @@ Object.defineProperty(exports, "buildProbeArgs", {
 		return buildProbeArgs;
 	}
 });
+Object.defineProperty(exports, "classifyProxyDenial", {
+	enumerable: true,
+	get: function() {
+		return classifyProxyDenial;
+	}
+});
 Object.defineProperty(exports, "collectTurnActivityRecords", {
 	enumerable: true,
 	get: function() {