Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

fix(desktop): verify ACP authentication status and retain diagnostics

tianma-if28a8792e1a67
diff --git a/apps/desktop/src/main/acp-host.mjs b/apps/desktop/src/main/acp-host.mjs
index 52df4516..af3e7fd4 100644
--- a/apps/desktop/src/main/acp-host.mjs
+++ b/apps/desktop/src/main/acp-host.mjs
@@ -298,6 +298,7 @@ export function isAuthRequiredError(error) {
export function sanitizeFailureDetail(error) {
const message = error instanceof Error ? error.message : String(error?.message ?? error ?? "");
let text = message.replace(/\s+/g, " ").trim();
+ text = text.replace(/https?:\/\/[^\s"']+/gi, "[url]");
const home = homedir();
if (home && home !== "/" && home !== "\\") text = text.split(home).join("[path]");
text = text.replace(/~\/[^\s]+/g, "[path]");
@@ -305,6 +306,8 @@ export function sanitizeFailureDetail(error) {
text = text.replace(/[A-Za-z]:\\(?:[^\\/:*?"<>|\r\n]+\\)*[^\\/:*?"<>|\r\n]*/g, "[path]");
text = text.replace(/\b(?:[A-Za-z0-9_]*(?:key|token|secret|password|credential)[A-Za-z0-9_]*)=[^\s]+/gi, "[redacted]");
text = text.replace(/\b(?:bearer|authorization)\s+[^\s]+/gi, "[redacted]");
+ text = text.replace(/(["']?[\w-]*(?:key|token|secret|password|credential|authorization)[\w-]*["']?\s*[:=]\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,}]+)/gi, "$1[redacted]");
+ text = text.replace(/\b(?:sk-ant-|sk-)[A-Za-z0-9_-]+/g, "[redacted]");
text = text.replace(/\s+/g, " ").trim();
if (!text || text === "[path]" || text === "[redacted]") return "connection_failed";
return text.slice(0, 160);
@@ -511,7 +514,7 @@ export function createAcpSpawnPlan(input, cwd) {
args: spec.args,
options: {
cwd: workspace,
- stdio: ["pipe", "pipe", "ignore"],
+ stdio: ["pipe", "pipe", "pipe"],
windowsHide: true,
shell: false,
...(spec.env || spec.unsetEnv ? { env: (() => {
@@ -525,7 +528,7 @@ export function createAcpSpawnPlan(input, cwd) {
export function spawnAcpChild(spawnImpl, command, cwd) {
const plan = createAcpSpawnPlan(command, cwd);
- const options = { ...plan.options, shell: false, stdio: ["pipe", "pipe", "ignore"] };
+ const options = { ...plan.options, shell: false, stdio: ["pipe", "pipe", "pipe"] };
if (options.shell !== false) throw new Error("ACP processes cannot use a shell");
const child = spawnImpl(plan.command, plan.args, options);
trackChild(child);
@@ -632,7 +635,10 @@ export function automaticAcpPermissionResponse(params) {
return { outcome: option ? { outcome: "selected", optionId: option.optionId } : { outcome: "cancelled" } };
}
-const createEdgeEverAcpClient = (requestId, emit, allowPermissions) => ({
+const createEdgeEverAcpClient = (requestId, emit, allowPermissions, onAuthStatus) => ({
+ extNotification(method, params) {
+ if (method === "_auth/status_update") onAuthStatus?.(params?.authStatus);
+ },
requestPermission(params) {
// Probe, install, and sign-in sessions do not originate from a user prompt.
return allowPermissions ? automaticAcpPermissionResponse(params) : { outcome: { outcome: "cancelled" } };
@@ -735,14 +741,52 @@ export function createAcpHostRuntime(options = {}) {
let child = null;
let authMethods = [];
let authenticationPending = false;
+ let authStatusKind;
+ let connected = false;
+ let resolveAuthStatus;
+ let authStatusReceived = new Promise((resolve) => { resolveAuthStatus = resolve; });
+ const onAuthStatus = (status) => {
+ if (!status || !["none", "account", "api_key", "gateway", "external"].includes(status.kind)) return;
+ authStatusKind = status.kind;
+ resolveAuthStatus();
+ if (connected && status.kind === "none") abort();
+ };
const abort = () => stopChild(child);
signal?.addEventListener("abort", abort, { once: true });
try {
if (signal?.aborted) throw Object.assign(new Error("connection_timeout"), { code: "TIMEOUT" });
child = await spawnAcpChild(spawnImpl, command, cwd);
if (signal?.aborted) throw Object.assign(new Error("connection_timeout"), { code: "TIMEOUT" });
+ // Drain stderr even when no logger is configured. Bound each connection's
+ // diagnostic output and sanitize before crossing into the log callback.
+ const secretValues = [
+ ...Object.entries({ ...process.env, ...(typeof command === "object" ? command.env : {}) }),
+ ...mcpServers.flatMap((server) => (server.env ?? []).map(({ name, value }) => [name, value])),
+ ].filter(([key, value]) => /key|token|secret|password|credential|authorization/i.test(key) && typeof value === "string" && value.length > 0)
+ .map(([, value]) => value).sort((a, b) => b.length - a.length);
+ let diagnosticBytes = 0;
+ let stderrBuffer = "";
+ const recordStderr = (line) => {
+ if (!line.trim() || diagnosticBytes >= 16_384) return;
+ diagnosticBytes += Buffer.byteLength(line);
+ for (const secret of secretValues) line = line.split(secret).join("[redacted]");
+ try { options.onDiagnostic?.({ requestId, message: sanitizeFailureDetail(line) }); } catch { /* diagnostics are optional */ }
+ };
+ child.stderr?.setEncoding?.("utf8");
+ child.stderr?.on("data", (chunk) => {
+ if (diagnosticBytes >= 16_384) return;
+ stderrBuffer += String(chunk);
+ let newline;
+ while ((newline = stderrBuffer.indexOf("\n")) !== -1) {
+ recordStderr(stderrBuffer.slice(0, newline));
+ stderrBuffer = stderrBuffer.slice(newline + 1);
+ }
+ // Never log a partial line: a secret can span pipe chunks.
+ if (stderrBuffer.length > 16_384) { stderrBuffer = ""; diagnosticBytes = 16_384; }
+ });
+ child.stderr?.on("end", () => { recordStderr(stderrBuffer); stderrBuffer = ""; });
const stream = acpNdJsonStream(child);
- const connection = new ClientSideConnection(() => createEdgeEverAcpClient(requestId, emit, allowPermissions), stream);
+ const connection = new ClientSideConnection(() => createEdgeEverAcpClient(requestId, emit, allowPermissions, onAuthStatus), stream);
void connection.closed?.catch(() => {});
const initialized = await connection.initialize(acpInitializeParams(version));
authMethods = publicAuthMethods(initialized);
@@ -757,11 +801,30 @@ export function createAcpHostRuntime(options = {}) {
if (authMethodId) {
if (!authMethods.some((method) => method.id === authMethodId)) throw new Error("invalid_auth_method");
authenticationPending = true;
+ if (authStatusKind === "none") {
+ authStatusKind = undefined;
+ authStatusReceived = new Promise((resolve) => { resolveAuthStatus = resolve; });
+ }
if (workBuddyAuth) await authenticateWorkBuddy(workBuddyAuth, authMethodId, signal, { readCredential });
else await connection.authenticate({ methodId: authMethodId });
authenticationPending = false;
}
+ if (authStatusKind === "none") throw RequestError.authRequired();
const session = await connection.newSession({ cwd, mcpServers });
+ // The extension is pushed asynchronously after initialize. Only agents
+ // advertising it must answer; older ACP adapters keep their existing path.
+ if (initialized?.agentCapabilities?._meta?.authStatus != null && authStatusKind === undefined) {
+ let timer;
+ try {
+ await Promise.race([
+ authStatusReceived,
+ new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("identity_status_unavailable")), options.authStatusTimeoutMs ?? 5_500); }),
+ connection.closed.then(() => { throw new Error("connection_closed"); }),
+ ]);
+ } finally { clearTimeout(timer); }
+ }
+ if (authStatusKind === "none") throw RequestError.authRequired();
+ connected = true;
if (signal?.aborted) throw Object.assign(new Error("connection_timeout"), { code: "TIMEOUT" });
return {
cwd,
@@ -771,13 +834,15 @@ export function createAcpHostRuntime(options = {}) {
authMethods,
promptCapabilities: normalizePromptCapabilities(initialized),
stop: abort,
+ authenticationRequired: () => authStatusKind === "none",
};
} catch (error) {
- if (authMethods.length && error && typeof error === "object") error.authMethods = authMethods;
- if (authenticationPending && error && typeof error === "object") error.authenticationPending = true;
+ const failure = authStatusKind === "none" && !authenticationPending ? RequestError.authRequired() : error;
+ if (authMethods.length && failure && typeof failure === "object") failure.authMethods = authMethods;
+ if (authenticationPending && failure && typeof failure === "object") failure.authenticationPending = true;
abort();
await removeAcpWorkspace(cwd, rmImpl);
- throw error;
+ throw failure;
} finally {
signal?.removeEventListener("abort", abort);
}
@@ -1031,7 +1096,7 @@ export function createAcpHostRuntime(options = {}) {
};
void connected.connection.prompt({ sessionId: connected.sessionId, prompt: content.blocks }).then((result) => {
if (session.cancelled) return finish({ requestId, type: "done" });
- const failure = promptResultFailure(result);
+ const failure = connected.authenticationRequired() ? "needs_login" : promptResultFailure(result);
if (failure === "needs_login") {
rememberPromptStatus({ state: "needs_login", authMethods: connected.authMethods });
}
@@ -1039,7 +1104,7 @@ export function createAcpHostRuntime(options = {}) {
}).catch((error) => {
if (session.cancelled) finish({ requestId, type: "done" });
else {
- const failure = classifyAcpFailure(error);
+ const failure = connected.authenticationRequired() ? { state: "needs_login" } : classifyAcpFailure(error);
if (failure.state === "needs_login") {
rememberPromptStatus({ state: "needs_login", authMethods: connected.authMethods });
}
diff --git a/apps/desktop/src/main/acp-host.test.mjs b/apps/desktop/src/main/acp-host.test.mjs
index fef55b88..0eea1c6b 100644
--- a/apps/desktop/src/main/acp-host.test.mjs
+++ b/apps/desktop/src/main/acp-host.test.mjs
@@ -84,7 +84,7 @@ const collector = () => {
};
};
-const fakeAgentSource = ({ reportPath, secretPath, allowImage, allowEmbedded, hold, requireAuth, advertiseAuth, promptRefusal, hangAuth, hangSession, workBuddyAccountApi, workBuddyLoginFailure, workBuddyUnreadable, workBuddyUnreadableAfterLogin, authMethodId = "browser" }) => `#!/usr/bin/env bun
+const fakeAgentSource = ({ reportPath, secretPath, allowImage, allowEmbedded, hold, requireAuth, advertiseAuth, promptRefusal, hangAuth, hangSession, workBuddyAccountApi, workBuddyLoginFailure, workBuddyUnreadable, workBuddyUnreadableAfterLogin, authMethodId = "browser", authStatusKind, advertiseAuthStatus = false, authStatusDelay = 20, stderrText, promptAuthStatusKind }) => `#!/usr/bin/env bun
import * as acp from ${JSON.stringify(sdkHref)};
import { writeFileSync, readFileSync } from "node:fs";
@@ -161,11 +161,19 @@ const stream = acp.ndJsonStream(
acp.agent({ name: "edgeever-fake-agent" })
.onRequest("initialize", (ctx) => {
+ if (${stderrText ? "true" : "false"}) {
+ const diagnostic = ${JSON.stringify(stderrText ?? "")};
+ process.stderr.write(diagnostic.slice(0, 12));
+ setTimeout(() => process.stderr.write(diagnostic.slice(12) + "\\n"), 5);
+ }
+ if (${authStatusKind ? "true" : "false"}) setTimeout(() => {
+ void ctx.client.notify("_auth/status_update", { authStatus: { kind: authenticated ? "api_key" : ${JSON.stringify(authStatusKind ?? "none")}, label: "Fixture" } });
+ }, ${authStatusDelay});
report.initialize = ctx.params;
save();
return {
protocolVersion: ctx.params.protocolVersion,
- agentCapabilities: { promptCapabilities: { image: allowImage, embeddedContext: allowEmbedded } },
+ agentCapabilities: { promptCapabilities: { image: allowImage, embeddedContext: allowEmbedded }, ...(${advertiseAuthStatus ? "true" : "false"} ? { _meta: { authStatus: {} } } : {}) },
authMethods: requireAuth || advertiseAuth ? [{ id: ${JSON.stringify(authMethodId)}, name: "Browser" }] : [],
};
})
@@ -177,6 +185,7 @@ acp.agent({ name: "edgeever-fake-agent" })
return new Promise(() => {});
}
authenticated = true;
+ if (${advertiseAuthStatus ? "true" : "false"}) void ctx.client.notify("_auth/status_update", { authStatus: { kind: "api_key", label: "Fixture" } });
save();
return {};
})
@@ -188,6 +197,9 @@ acp.agent({ name: "edgeever-fake-agent" })
return { sessionId: "sess-1" };
})
.onRequest("session/prompt", async (ctx) => {
+ if (${promptAuthStatusKind ? "true" : "false"}) {
+ await ctx.client.notify("_auth/status_update", { authStatus: { kind: ${JSON.stringify(promptAuthStatusKind ?? "none")}, label: "Fixture" } });
+ }
report.prompt = ctx.params.prompt;
save();
if (promptRefusal) return promptRefusal;
@@ -526,7 +538,7 @@ describe("ACP spawn and failure mapping", () => {
options: expect.objectContaining({ shell: false, cwd: path.resolve(workspace) }),
});
expect(captured.options.shell).toBe(false);
- expect(captured.options.stdio).toEqual(["pipe", "pipe", "ignore"]);
+ expect(captured.options.stdio).toEqual(["pipe", "pipe", "pipe"]);
await rm(workspace, { recursive: true, force: true });
});
@@ -696,6 +708,82 @@ describe("ACP stdio session", () => {
}
}, 15_000);
+ for (const kind of ["none", "account", "api_key", "gateway", "external", undefined]) {
+ sessionTest(`handles delayed auth identity ${kind ?? "not reported"} with successful session/new`, async () => {
+ const directory = await mkdtemp(path.join(tmpdir(), "edgeever-acp-identity-"));
+ const reportPath = path.join(directory, "report.json");
+ try {
+ const scriptPath = await writeFakeAgent(directory, { reportPath, authStatusKind: kind, advertiseAuthStatus: true, authStatusDelay: 80 });
+ const runtime = createAcpHostRuntime({
+ authStatusTimeoutMs: 200,
+ adapterManager: { get: () => ({ command: { command: process.execPath, args: [scriptPath] } }) },
+ });
+ const result = await runtime.probeAdapter({ id: "claudeCode" });
+ expect(result.state).toBe(kind === "none" ? "needs_login" : kind ? "available" : "failed");
+ if (!kind) expect(result.detail).toBe("identity_status_unavailable");
+ expect((await readReport(reportPath)).newSession).not.toBeNull();
+ await waitUntilExited(Number(await readFile(`${reportPath}.pid`, "utf8")));
+ if (kind === "none") {
+ const events = [];
+ await runtime.prompt({ adapterId: "claudeCode", prompt: "hello", noteAccess: false }, (event) => events.push(event));
+ expect(events.at(-1)).toMatchObject({ type: "error", message: "needs_login" });
+ expect((await readReport(reportPath)).prompt).toBeNull();
+ await waitUntilExited(Number(await readFile(`${reportPath}.pid`, "utf8")));
+ }
+ } finally { await rm(directory, { recursive: true, force: true }); }
+ }, 15_000);
+ }
+
+ sessionTest("accepts new credentials after authentication and ignores the earlier logged-out identity", async () => {
+ const directory = await mkdtemp(path.join(tmpdir(), "edgeever-acp-identity-login-"));
+ const reportPath = path.join(directory, "report.json");
+ try {
+ const scriptPath = await writeFakeAgent(directory, { reportPath, authStatusKind: "none", advertiseAuthStatus: true, advertiseAuth: true });
+ const runtime = createAcpHostRuntime({ adapterManager: { get: () => ({ command: { command: process.execPath, args: [scriptPath] } }) } });
+ expect((await runtime.probeAdapter({ id: "claudeCode" })).state).toBe("needs_login");
+ await waitUntilExited(Number(await readFile(`${reportPath}.pid`, "utf8")));
+ expect((await runtime.authenticateAdapter({ id: "claudeCode", methodId: "browser" })).state).toBe("available");
+ await waitUntilExited(Number(await readFile(`${reportPath}.pid`, "utf8")));
+ } finally { await rm(directory, { recursive: true, force: true }); }
+ }, 15_000);
+
+ sessionTest("reports credentials revoked during a live prompt as needs_login", async () => {
+ const directory = await mkdtemp(path.join(tmpdir(), "edgeever-acp-identity-expired-"));
+ const reportPath = path.join(directory, "report.json");
+ try {
+ const scriptPath = await writeFakeAgent(directory, { reportPath, authStatusKind: "api_key", advertiseAuthStatus: true, promptAuthStatusKind: "none", hold: true });
+ const runtime = createAcpHostRuntime({ adapterManager: { get: () => ({ command: { command: process.execPath, args: [scriptPath] } }) } });
+ const collected = collector();
+ await runtime.prompt({ adapterId: "claudeCode", prompt: "hello", noteAccess: false }, collected.emit);
+ expect(await collected.waitFor((event) => event.type === "error")).toMatchObject({ message: "needs_login" });
+ expect(runtime.listAdapters().find((adapter) => adapter.id === "claudeCode").state).toBe("needs_login");
+ await waitUntilExited(Number(await readFile(`${reportPath}.pid`, "utf8")));
+ } finally { await rm(directory, { recursive: true, force: true }); }
+ }, 15_000);
+
+ sessionTest("drains split stderr and records only sanitized diagnostics", async () => {
+ const directory = await mkdtemp(path.join(tmpdir(), "edgeever-acp-stderr-"));
+ const reportPath = path.join(directory, "report.json");
+ try {
+ const diagnostics = [];
+ const scriptPath = await writeFakeAgent(directory, {
+ reportPath, advertiseAuthStatus: true, authStatusKind: "api_key", authStatusDelay: 80,
+ stderrText: 'Query closed before response received opaque-secret-value {"api_key":"sk-ant-secret-value"} https://gateway.test/path?key=secret',
+ });
+ const runtime = createAcpHostRuntime({
+ onDiagnostic: (details) => diagnostics.push(details),
+ adapterManager: { get: () => ({ command: { command: process.execPath, args: [scriptPath], env: { ANTHROPIC_API_KEY: "opaque-secret-value" } } }) },
+ });
+ expect((await runtime.probeAdapter({ id: "claudeCode" })).state).toBe("available");
+ const logged = JSON.stringify(diagnostics);
+ expect(logged).toContain("Query closed before response received");
+ expect(logged).not.toContain("secret-value");
+ expect(logged).not.toContain("opaque-secret-value");
+ expect(logged).not.toContain("gateway.test");
+ await waitUntilExited(Number(await readFile(`${reportPath}.pid`, "utf8")));
+ } finally { await rm(directory, { recursive: true, force: true }); }
+ }, 15_000);
+
sessionTest("a managed Codex connector is unchecked after restart and becomes available after a real probe", async () => {
const directory = await mkdtemp(path.join(tmpdir(), "edgeever-acp-restart-"));
try {
diff --git a/apps/desktop/src/main/index.mjs b/apps/desktop/src/main/index.mjs
index 6d48d522..f4d5eab4 100644
--- a/apps/desktop/src/main/index.mjs
+++ b/apps/desktop/src/main/index.mjs
@@ -1777,6 +1777,7 @@ const startApplication = async () => {
});
const acpRuntime = registerAcpIpc(ipcMain, createAcpHostRuntime({
adapterStore: join(app.getPath("userData"), "acp-adapters"),
+ onDiagnostic: (details) => { void writeDiagnostic("acp.adapter-stderr", details); },
mcpScriptPath: app.isPackaged
? join(process.resourcesPath, "mcp-bridge", "edgeever-mcp-stdio.mjs")
: join(projectRoot, "scripts", "edgeever-mcp-stdio.mjs"),
diff --git a/apps/web/src/components/ai-sidebar/AiSidebar.tsx b/apps/web/src/components/ai-sidebar/AiSidebar.tsx
index da1e0482..47b8ab25 100644
--- a/apps/web/src/components/ai-sidebar/AiSidebar.tsx
+++ b/apps/web/src/components/ai-sidebar/AiSidebar.tsx
@@ -999,6 +999,8 @@ function AiSidebarSession({
const noteAccessErrorKey = desktopAcpNoteAccessErrorKey(event.message);
setError(noteAccessErrorKey ? t(noteAccessErrorKey)
: event.message === "workbuddy_credentials_unavailable" ? t("aiAssistant.agentSource.workbuddyCredentialsUnavailable")
+ : event.message === "identity_status_unavailable" ? t("aiAssistant.agentSource.identityStatusUnavailable")
+ : event.message === "needs_login" && localAdapterId === "claudeCode" ? t("aiAssistant.agentSource.claudeCodeLoginHint")
: event.message === "needs_login" ? t(localAdapterId === "workbuddyCn" || localAdapterId === "workbuddyIntl"
? "aiAssistant.sidebar.workbuddyLoginRequired" : "aiAssistant.sidebar.localLoginRequired")
: event.message === "agent_refused" ? t("aiAssistant.sidebar.agentRefused") : event.message);
diff --git a/apps/web/src/components/settings/DesktopAcpAgentCard.tsx b/apps/web/src/components/settings/DesktopAcpAgentCard.tsx
index 35d7610a..d3d75abc 100644
--- a/apps/web/src/components/settings/DesktopAcpAgentCard.tsx
+++ b/apps/web/src/components/settings/DesktopAcpAgentCard.tsx
@@ -47,6 +47,8 @@ const statusKey = (adapter: DesktopAcpAdapter | undefined, probing: boolean) =>
if (!adapter || adapter.detail === "not_probed") return "aiAssistant.agentSource.notProbed";
if (adapter.detail === "workbuddy_credentials_unavailable") return "aiAssistant.agentSource.workbuddyCredentialsUnavailable";
if (adapter.detail === "authentication_timeout") return "aiAssistant.agentSource.authenticationTimedOut";
+ if (adapter.detail === "identity_status_unavailable") return "aiAssistant.agentSource.identityStatusNotReported";
+ if (adapter.id === "claudeCode" && adapter.state === "needs_login") return "aiAssistant.agentSource.claudeCodeCredentialsRequired";
if (adapter.detail === "authentication_failed") return "aiAssistant.agentSource.authenticationFailed";
if (adapter.detail === "invalid_path") return "aiAssistant.agentSource.invalidPath";
if (adapter.detail === "desktop_unavailable") return "aiAssistant.agentSource.localDisabled";
@@ -154,6 +156,7 @@ const DesktopAcpAgentCardBody = ({ bridge }: { bridge: boolean }) => {
shown?.state === "needs_login" ||
(shown?.state === "available" && (isWorkBuddy || authMethods.length > 0)) ||
shown?.updateError ||
+ shown?.detail === "identity_status_unavailable" ||
adapterId === "openClaw" ||
(adapterId === "hermesAgent" && shown?.state === "failed")
);
@@ -397,6 +400,12 @@ const DesktopAcpAgentCardBody = ({ bridge }: { bridge: boolean }) => {
{t(adapterId === "claudeCode" ? "aiAssistant.agentSource.claudeCodeMissingHint" : adapterId === "openClaw" ? "aiAssistant.agentSource.openClawMissingHint" : adapterId === "hermesAgent" ? "aiAssistant.agentSource.hermesAgentMissingHint" : adapterId === "grokBuild" ? "aiAssistant.agentSource.grokBuildMissingHint" : adapterId === "deepseekHarness" ? "aiAssistant.agentSource.deepseekHarnessMissingHint" : adapterId === "piAgent" ? shown.detail === "adapter_missing" ? "aiAssistant.agentSource.piAgentAdapterMissingHint" : "aiAssistant.agentSource.piAgentMissingHint" : adapterId === "workbuddyCn" || adapterId === "workbuddyIntl" ? "aiAssistant.agentSource.workbuddyMissingHint" : "aiAssistant.agentSource.installHint")}
</p>
) : null}
+ {shown?.detail === "identity_status_unavailable" ? (
+ <p>{t("aiAssistant.agentSource.identityStatusUnavailable")}</p>
+ ) : null}
+ {shown?.state === "needs_login" && adapterId === "claudeCode" ? (
+ <p>{t("aiAssistant.agentSource.claudeCodeLoginHint")}</p>
+ ) : null}
{shown?.state === "needs_login" && adapterId === "piAgent" ? (
<p>{t("aiAssistant.agentSource.piAgentLoginHint")}</p>
) : null}
diff --git a/docs/claude-code-gateway.md b/docs/claude-code-gateway.md
new file mode 100644
index 00000000..17d4cf58
--- /dev/null
+++ b/docs/claude-code-gateway.md
@@ -0,0 +1,30 @@
+# Claude Code with a custom gateway
+
+The desktop Claude Code connector runs locally. Its credentials and model configuration belong to Claude Code, independently of the AI providers configured on your EdgeEver instance.
+
+Apps launched from Finder or Dock do not read `~/.zshrc`. Put persistent Claude Code configuration in the user-level `~/.claude/settings.json` instead of relying only on shell exports. EdgeEver creates temporary ACP workspaces, so settings in your development project's `.claude/` directory do not configure those sessions.
+
+Merge this example into your existing user settings; do not overwrite unrelated settings. Replace the endpoint, key, and model ID with values accepted by your gateway:
+
+```json
+{
+ "model": "opus",
+ "env": {
+ "ANTHROPIC_BASE_URL": "https://your-gateway.example",
+ "ANTHROPIC_API_KEY": "your-api-key",
+ "ANTHROPIC_DEFAULT_OPUS_MODEL": "your-gateway-full-model-id"
+ }
+}
+```
+
+This selects the `opus` family and maps it to the gateway's full model ID. If you select Sonnet or Haiku, configure the corresponding `ANTHROPIC_DEFAULT_SONNET_MODEL` or `ANTHROPIC_DEFAULT_HAIKU_MODEL` mapping as well. Follow your gateway's authentication instructions if it uses `ANTHROPIC_AUTH_TOKEN` instead of `ANTHROPIC_API_KEY`; do not set conflicting credentials.
+
+Keep this file private: it contains credentials. Existing shell environment variables can also affect model selection; the connector gives `ANTHROPIC_MODEL` priority over the `model` setting. If you start EdgeEver from a terminal, check for conflicting exports.
+
+In EdgeEver, open **Settings → Models & Agents**, select **Claude Code**, and check the connection again. Then send a short message to verify the gateway actually accepts the configured model. A successful connection check does not verify model access, gateway availability, or billing quota.
+
+When the adapter explicitly reports no credentials, EdgeEver displays **Not signed in / missing credentials**. When it advertises authentication reporting but does not return a status, EdgeEver reports that authentication status could not be verified. Older connectors without this extension retain their session-based connection check.
+
+Adapter stderr is recorded as bounded, sanitized `acp.adapter-stderr` events in `desktop.log`. On macOS the default location is `~/Library/Application Support/EdgeEver/logs/desktop.log`; a custom desktop data directory changes this location. Review logs before sharing them, and never share your settings file or credentials.
+
+References: [Claude Code settings](https://code.claude.com/docs/en/settings), [model configuration](https://code.claude.com/docs/en/model-config).
diff --git a/docs/claude-code-gateway.zh-CN.md b/docs/claude-code-gateway.zh-CN.md
new file mode 100644
index 00000000..8db9180e
--- /dev/null
+++ b/docs/claude-code-gateway.zh-CN.md
@@ -0,0 +1,30 @@
+# Claude Code 自建网关配置
+
+桌面端 Claude Code 连接组件在本机运行。凭证和模型配置属于 Claude Code,与 EdgeEver 实例中配置的 AI 服务商相互独立。
+
+从 Finder 或 Dock 启动的应用不会读取 `~/.zshrc`。请将持久配置写入用户级 `~/.claude/settings.json`,不要仅依赖 shell 中的 export。EdgeEver 为 ACP 创建临时工作目录,因此开发项目 `.claude/` 目录中的配置不会配置这些会话。
+
+将下面的示例合并到已有用户配置中,不要覆盖其他设置。将地址、密钥和模型 ID 替换成网关接受的实际值:
+
+```json
+{
+ "model": "opus",
+ "env": {
+ "ANTHROPIC_BASE_URL": "https://your-gateway.example",
+ "ANTHROPIC_API_KEY": "your-api-key",
+ "ANTHROPIC_DEFAULT_OPUS_MODEL": "your-gateway-full-model-id"
+ }
+}
+```
+
+该配置选择 `opus` 系列,并将其映射到网关的完整模型 ID。如果选择 Sonnet 或 Haiku,还需配置对应的 `ANTHROPIC_DEFAULT_SONNET_MODEL` 或 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。如果网关要求使用 `ANTHROPIC_AUTH_TOKEN` 而非 `ANTHROPIC_API_KEY`,请遵循网关说明,避免设置相互冲突的凭证。
+
+该文件包含凭证,请妥善保管。已有 shell 环境变量也可能影响模型选择;连接组件优先使用 `ANTHROPIC_MODEL`,其次使用 `model` 设置。从终端启动 EdgeEver 时,请检查是否有冲突的 export。
+
+在 EdgeEver 的“设置 → 模型与代理”中选择“Claude Code”,重新检查连接,再发送一条简短消息确认网关实际接受配置的模型。连接检查成功不能验证模型权限、网关可用性或计费额度。
+
+适配器明确报告没有凭证时,EdgeEver 显示“未登录 / 缺少凭证”。适配器声明支持认证状态报告但没有返回状态时,EdgeEver 提示无法验证认证状态。没有该扩展的旧连接组件保留基于会话创建的连接检查方式。
+
+适配器 stderr 经过限量、脱敏后,以 `acp.adapter-stderr` 事件写入 `desktop.log`。macOS 默认位置为 `~/Library/Application Support/EdgeEver/logs/desktop.log`;自定义桌面数据目录会改变此位置。分享前请检查日志,不要分享配置文件或凭证。
+
+参考:[Claude Code 配置](https://code.claude.com/docs/en/settings)、[模型配置](https://code.claude.com/docs/en/model-config)。
diff --git a/packages/shared/src/i18n/en-US.ts b/packages/shared/src/i18n/en-US.ts
index 6eea2013..53ef1f90 100644
--- a/packages/shared/src/i18n/en-US.ts
+++ b/packages/shared/src/i18n/en-US.ts
@@ -1737,6 +1737,10 @@ export const enUS = {
install: "Install connector",
installHint: "When a local agent is detected, its connector downloads from the official source. This may exceed 100 MiB; updates are checked automatically.",
claudeCodeNotFound: "Claude Code ACP connector not found",
+ claudeCodeCredentialsRequired: "Not signed in / missing credentials",
+ claudeCodeLoginHint: "Claude Code credentials are missing. Sign in to Claude Code in a terminal, or configure gateway credentials in ~/.claude/settings.json; apps launched from Dock do not read ~/.zshrc. For a custom gateway, configure ANTHROPIC_BASE_URL and map opus to its full model ID with ANTHROPIC_DEFAULT_OPUS_MODEL, then check the connection again.",
+ identityStatusNotReported: "Authentication status not reported",
+ identityStatusUnavailable: "The agent did not report its authentication status. Check its configuration and desktop.log, then try again.",
claudeCodeMissingHint: "Click “Install connector” to let EdgeEver install it and check the connection.",
openClawNotFound: "OpenClaw CLI not found",
openClawMissingHint: "Install OpenClaw CLI and start its Gateway, then check the connection.",
diff --git a/packages/shared/src/i18n/ja.ts b/packages/shared/src/i18n/ja.ts
index 7d507a93..4ce54c18 100644
--- a/packages/shared/src/i18n/ja.ts
+++ b/packages/shared/src/i18n/ja.ts
@@ -1726,6 +1726,10 @@ export const ja = {
install: "接続コンポーネントをインストール",
installHint: "ローカルのエージェントを検出すると、公式配布元からダウンロードします。100 MiB を超える場合があり、インストール後は更新を自動確認します。",
claudeCodeNotFound: "Claude Code ACP 接続コンポーネントが見つかりません",
+ claudeCodeCredentialsRequired: "未ログイン / 認証情報がありません",
+ claudeCodeLoginHint: "Claude Code の認証情報がありません。ターミナルで Claude Code にログインするか、~/.claude/settings.json にゲートウェイの認証情報を設定してください。Dock から起動したアプリは ~/.zshrc を読み込みません。カスタムゲートウェイでは ANTHROPIC_BASE_URL を設定し、ANTHROPIC_DEFAULT_OPUS_MODEL で opus を完全なモデル ID に対応させてから、接続を再確認してください。",
+ identityStatusNotReported: "認証状態が報告されていません",
+ identityStatusUnavailable: "Agent が認証状態を報告しませんでした。設定と desktop.log を確認して再試行してください。",
claudeCodeMissingHint: "「接続コンポーネントをインストール」をクリックすると、EdgeEver がインストールして接続を確認します。",
openClawNotFound: "OpenClaw CLI が見つかりません",
openClawMissingHint: "OpenClaw CLI をインストールして Gateway を起動し、接続を確認してください。",
diff --git a/packages/shared/src/i18n/pl.ts b/packages/shared/src/i18n/pl.ts
index 5a31ee74..0dc06146 100644
--- a/packages/shared/src/i18n/pl.ts
+++ b/packages/shared/src/i18n/pl.ts
@@ -1726,6 +1726,10 @@ export const pl = {
install: "Zainstaluj konektor",
installHint: "Po wykryciu lokalnego agenta jego konektor jest pobierany z oficjalnego źródła. Może zajmować ponad 100 MiB; aktualizacje są sprawdzane automatycznie.",
claudeCodeNotFound: "Nie znaleziono konektora Claude Code ACP",
+ claudeCodeCredentialsRequired: "Brak logowania / danych uwierzytelniających",
+ claudeCodeLoginHint: "Brak danych uwierzytelniających Claude Code. Zaloguj się do Claude Code w terminalu lub skonfiguruj dane bramy w ~/.claude/settings.json; aplikacje uruchamiane z Docka nie odczytują ~/.zshrc. Dla własnej bramy ustaw ANTHROPIC_BASE_URL i przypisz pełny identyfikator modelu do opus przez ANTHROPIC_DEFAULT_OPUS_MODEL, a następnie sprawdź połączenie ponownie.",
+ identityStatusNotReported: "Nie zgłoszono stanu uwierzytelnienia",
+ identityStatusUnavailable: "Agent nie zgłosił stanu uwierzytelnienia. Sprawdź konfigurację i desktop.log, a następnie spróbuj ponownie.",
claudeCodeMissingHint: "Kliknij „Zainstaluj konektor”, aby EdgeEver zainstalował go i sprawdził połączenie.",
openClawNotFound: "Nie znaleziono OpenClaw CLI",
openClawMissingHint: "Zainstaluj OpenClaw CLI i uruchom Gateway, a następnie sprawdź połączenie.",
diff --git a/packages/shared/src/i18n/zh-CN.ts b/packages/shared/src/i18n/zh-CN.ts
index c55a8e37..ececd957 100644
--- a/packages/shared/src/i18n/zh-CN.ts
+++ b/packages/shared/src/i18n/zh-CN.ts
@@ -1737,6 +1737,10 @@ export const zhCN = {
install: "安装连接组件",
installHint: "检测到本机 Agent 后会从官方来源下载,可能超过 100 MiB;安装后会自动检查更新。",
claudeCodeNotFound: "未找到 Claude Code ACP 连接组件",
+ claudeCodeCredentialsRequired: "未登录 / 缺少凭证",
+ claudeCodeLoginHint: "Claude Code 缺少凭证。请在终端完成 Claude Code 登录,或在 ~/.claude/settings.json 配置网关凭证;从 Dock 启动的应用不会读取 ~/.zshrc。自建网关还需配置 ANTHROPIC_BASE_URL,并用 ANTHROPIC_DEFAULT_OPUS_MODEL 将 opus 映射到完整模型 ID,然后重新检查连接。",
+ identityStatusNotReported: "未报告认证状态",
+ identityStatusUnavailable: "Agent 未报告认证状态。请检查配置和 desktop.log 后重试。",
claudeCodeMissingHint: "点击“安装连接组件”,EdgeEver 会自动安装并检查连接。",
openClawNotFound: "未找到 OpenClaw CLI",
openClawMissingHint: "请先安装 OpenClaw CLI 并启动 Gateway,再检查连接。",