refactor: move API key prompt into main app lifecycle

Allow the agent to start without an LLM client and prompt for an API key within the app, rather than blocking startup. This enables deferred configuration and better error handling for invalid keys.

Author: tomcant

src/adapters/llm/anthropic.ts

@@ -6,11 +6,16 @@ export function anthropicFromEnv(
   env: Record<string, string | undefined>,
   systemPrompt?: string,
 ): AnthropicLlmClient | null {
-  if (!env.ANTHROPIC_API_KEY) {
+  const apiKey = env.ANTHROPIC_API_KEY;
+  if (!apiKey) return null;
+
+  // A custom base URL means a proxy or gateway, whose keys use their own format.
+  if (!env.ANTHROPIC_BASE_URL && !apiKey.startsWith("sk-ant-")) {
     return null;
   }
+
   return new AnthropicLlmClient(
-    new Anthropic({ apiKey: env.ANTHROPIC_API_KEY }),
+    new Anthropic({ apiKey }),
     env.MODEL ?? "claude-sonnet-4-6",
     systemPrompt,
   );

src/agent/agent.ts

@@ -9,13 +9,18 @@ export class Agent {
   private messages: Message[] = [];
 
   constructor(
-    private readonly client: LlmClient,
+    private client: LlmClient | null,
     private readonly registry: ToolRegistry,
     private readonly session: Session,
     private readonly notices: string[] = [],
   ) {}
 
-  modelInfo(): ModelInfo {
+  setClient(client: LlmClient): void {
+    this.client = client;
+  }
+
+  modelInfo(): ModelInfo | null {
+    if (!this.client) return null;
     return { provider: this.client.provider, model: this.client.model };
   }
 
@@ -37,6 +42,10 @@ export class Agent {
   }
 
   async *turn(input: string, signal?: AbortSignal): AsyncGenerator<AgentEvent> {
+    if (!this.client) {
+      throw new Error("No LLM client is configured.");
+    }
+
     const userMessage: Message = {
       role: "user",
       content: [{ type: "text", text: input }],

src/agent/factory.ts

@@ -14,7 +14,7 @@ type CreateAgentOptions = {
 };
 
 export async function createAgent(
-  llmClient: LlmClient,
+  llmClient: LlmClient | null,
   options: CreateAgentOptions = {},
 ): Promise<Agent> {
   const toolDir = await createToolDir(options.toolDir);

src/index.ts

@@ -6,50 +6,22 @@ import { createDemoAgent } from "./demo";
 import systemPrompt from "./prompt.md";
 import { App } from "./tui/App.tsx";
 import { initColorScheme } from "./tui/color-scheme.ts";
-import { ApiKeyPrompt } from "./tui/components/ApiKeyPrompt.tsx";
 
 await initColorScheme();
 
 const agent =
   process.env.DEMO === "1"
     ? await createDemoAgent()
-    : await createAgent(await resolveLlmClientInteractive());
+    : await createAgent(resolveLlmClient(systemPrompt));
 
-const { waitUntilExit } = renderFullscreen(createElement(App, { agent }));
+const { waitUntilExit } = renderFullscreen(createElement(App, { agent, attachApiKey }));
 await waitUntilExit();
 
-async function resolveLlmClientInteractive() {
-  const configured = resolveLlmClient(systemPrompt);
-  if (configured) return configured;
-
-  const key = await promptForApiKey();
-  process.env.ANTHROPIC_API_KEY = key;
-
-  const client = resolveLlmClient(systemPrompt);
-  if (client) return client;
-
-  console.error("Error: could not initialise an LLM client from the provided key.");
-  process.exit(1);
-}
-
-function promptForApiKey(): Promise<string> {
-  return new Promise((resolve) => {
-    let submitted = false;
-    const { unmount, waitUntilExit } = renderFullscreen(
-      createElement(ApiKeyPrompt, {
-        onSubmit: (key: string) => {
-          submitted = true;
-          unmount();
-          resolve(key);
-        },
-      }),
-    );
-    void waitUntilExit().then(() => {
-      if (!submitted) {
-        process.exit(0);
-      }
-    });
-  });
+function attachApiKey(apiKey: string) {
+  const client = resolveLlmClient(systemPrompt, { ...process.env, ANTHROPIC_API_KEY: apiKey });
+  if (!client) return null;
+  agent.setClient(client);
+  return agent.modelInfo();
 }
 
 /*

src/tui/App.tsx

@@ -3,9 +3,10 @@ import { defaultTheme, extendTheme, Spinner, TextInput, ThemeProvider } from "@i
 import { Box, Text, useApp, useInput, useStdout } from "ink";
 import { ScrollView, type ScrollViewRef } from "ink-scroll-view";
 import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
-import type { Agent } from "#/agent";
+import type { Agent, ModelInfo } from "#/agent";
 import { isLightScheme } from "./color-scheme.ts";
 import { type Command, parseCommand } from "./commands.ts";
+import { ApiKeyPrompt } from "./components/ApiKeyPrompt.tsx";
 import { AssistantMessage } from "./components/AssistantMessage.tsx";
 import { Banner } from "./components/Banner.tsx";
 import { ErrorMessage } from "./components/ErrorMessage.tsx";
@@ -37,9 +38,10 @@ type OverlayState = {
 
 type AppProps = {
   agent: Agent;
+  attachApiKey: (apiKey: string) => ModelInfo | null;
 };
 
-export function App({ agent }: AppProps) {
+export function App({ agent, attachApiKey }: AppProps) {
   const { exit } = useApp();
   const { stdout } = useStdout();
   const [rows, setRows] = useState(stdout?.rows ?? 24);
@@ -51,6 +53,11 @@ export function App({ agent }: AppProps) {
   const [elapsedMs, setElapsedMs] = useState<number | null>(null);
   const [working, setWorking] = useState(false);
 
+  const [modelInfo, setModelInfo] = useState(agent.modelInfo());
+  const [apiKeyError, setApiKeyError] = useState<string>();
+  const [apiKeyAttempt, setApiKeyAttempt] = useState(0);
+  const needsApiKey = modelInfo === null;
+
   const scrollRef = useRef<ScrollViewRef>(null);
   const [scrollOffset, setScrollOffset] = useState(0);
   const [contentHeight, setContentHeight] = useState(0);
@@ -126,24 +133,41 @@ export function App({ agent }: AppProps) {
       case "tools_list":
         setOverlay(toolsOverlay());
         return;
+
       case "tools_remove":
         await agent.removeTool(command.name);
         appendSystemMessage(`Removed tool '${command.name}'`);
         setOverlay((prev) => (prev?.kind === "tools" ? toolsOverlay() : prev));
         return;
+
       case "clear":
         await agent.clear();
         setTranscript([]);
         setShowIntro(true);
         setOverlay(null);
         setElapsedMs(null);
         return;
+
       case "exit":
         exit();
         return;
     }
   };
 
+  const handleApiKeySubmit = (value: string) => {
+    const apiKey = value.trim();
+    if (apiKey === "") return;
+
+    const modelInfo = attachApiKey(apiKey);
+    if (!modelInfo) {
+      setApiKeyError("Could not initialise an LLM client from that key.");
+      setApiKeyAttempt((attempt) => attempt + 1);
+      return;
+    }
+
+    setModelInfo(modelInfo);
+  };
+
   const handleSubmit = async (input: string) => {
     if (input.trim() === "") return;
     setTextInputKey((k) => k + 1);
@@ -208,7 +232,15 @@ export function App({ agent }: AppProps) {
           >
             <Box key="header" flexDirection="column" paddingTop={1} gap={1}>
               <Banner />
-              {showIntro && <IntroMessage />}
+              {needsApiKey ? (
+                <ApiKeyPrompt
+                  key={apiKeyAttempt}
+                  error={apiKeyError}
+                  onSubmit={handleApiKeySubmit}
+                />
+              ) : (
+                showIntro && <IntroMessage />
+              )}
             </Box>
             {transcript.map((item) => (
               <Box key={`${item.kind}-${item.id}`} marginTop={1}>
@@ -248,25 +280,27 @@ export function App({ agent }: AppProps) {
             )}
           </Box>
           {overlay && <Overlay title={overlay.title}>{overlay.content}</Overlay>}
-          <Box
-            paddingX={1}
-            borderStyle="round"
-            borderColor={theme.accent}
-            borderDimColor={!isLightScheme()}
-          >
-            <Text color={theme.accent} bold>
-              ❯{" "}
-            </Text>
-            <Box flexGrow={1}>
-              <TextInput
-                key={textInputKey}
-                isDisabled={working}
-                placeholder="Type a message (Ctrl+C or /exit to quit)"
-                onSubmit={handleSubmit}
-              />
+          {!needsApiKey && (
+            <Box
+              paddingX={1}
+              borderStyle="round"
+              borderColor={theme.accent}
+              borderDimColor={!isLightScheme()}
+            >
+              <Text color={theme.accent} bold>
+                ❯{" "}
+              </Text>
+              <Box flexGrow={1}>
+                <TextInput
+                  key={textInputKey}
+                  isDisabled={working}
+                  placeholder="Type a message (Ctrl+C or /exit to quit)"
+                  onSubmit={handleSubmit}
+                />
+              </Box>
             </Box>
-          </Box>
-          <StatusBar {...agent.modelInfo()} />
+          )}
+          {modelInfo && <StatusBar {...modelInfo} />}
         </Box>
       </Box>
     </ThemeProvider>

src/tui/components/ApiKeyPrompt.tsx

@@ -1,35 +1,22 @@
 import { PasswordInput } from "@inkjs/ui";
 import { Box, Text } from "ink";
-import pkg from "../../../package.json" with { type: "json" };
 import { isLightScheme } from "../color-scheme.ts";
 import { theme } from "../theme.ts";
+import { ErrorMessage } from "./ErrorMessage.tsx";
 
 type ApiKeyPromptProps = {
-  onSubmit: (key: string) => void;
+  error?: string;
+  onSubmit: (apiKey: string) => void;
 };
 
-export function ApiKeyPrompt({ onSubmit }: ApiKeyPromptProps) {
-  const handleSubmit = (value: string) => {
-    const key = value.trim();
-    if (key === "") return;
-    onSubmit(key);
-  };
-
+export function ApiKeyPrompt({ error, onSubmit }: ApiKeyPromptProps) {
   return (
     <Box flexDirection="column" gap={1}>
-      <Box flexDirection="column" paddingX={1} gap={1}>
-        <Text>
-          <Text bold color={theme.accent}>
-            Agent Toolsmith
-          </Text>
-          <Text dimColor> v{pkg.version}</Text>
-        </Text>
+      <Box>
         <Text>
-          <Text dimColor>
-            No LLM provider is configured. Paste an Anthropic API key to continue, or press{" "}
-          </Text>
-          <Text color={theme.accent}>Ctrl+C</Text>
-          <Text dimColor> to quit.</Text>
+          <Text dimColor>No LLM provider is configured. Paste an </Text>
+          <Text color={theme.accent}>Anthropic API key</Text>
+          <Text dimColor> to continue, or press Ctrl+C to quit.</Text>
         </Text>
       </Box>
       <Box
@@ -38,10 +25,9 @@ export function ApiKeyPrompt({ onSubmit }: ApiKeyPromptProps) {
         borderColor={theme.accent}
         borderDimColor={!isLightScheme()}
       >
-        <Box flexGrow={1}>
-          <PasswordInput placeholder="sk-ant-..." onSubmit={handleSubmit} />
-        </Box>
+        <PasswordInput placeholder="sk-ant-..." onSubmit={onSubmit} />
       </Box>
+      {error && <ErrorMessage content={error} />}
     </Box>
   );
 }

tests/adapters/llm/resolve.test.ts

@@ -3,15 +3,15 @@ import { resolveLlmClient } from "#/adapters/llm/index.ts";
 
 describe("LLM client resolution", () => {
   test("returns an Anthropic client when ANTHROPIC_API_KEY is set", () => {
-    const client = resolveLlmClient(undefined, { ANTHROPIC_API_KEY: "test-key" });
+    const client = resolveLlmClient(undefined, { ANTHROPIC_API_KEY: "sk-ant-test" });
 
     expect(client?.provider).toBe("anthropic");
     expect(client?.model).toBe("claude-sonnet-4-6");
   });
 
   test("honours the MODEL override", () => {
     const client = resolveLlmClient(undefined, {
-      ANTHROPIC_API_KEY: "test-key",
+      ANTHROPIC_API_KEY: "sk-ant-test",
       MODEL: "claude-opus-4-8",
     });
 
@@ -21,4 +21,17 @@ describe("LLM client resolution", () => {
   test("returns null when no provider is configured", () => {
     expect(resolveLlmClient(undefined, {})).toBeNull();
   });
+
+  test("returns null for a key that is not an Anthropic key", () => {
+    expect(resolveLlmClient(undefined, { ANTHROPIC_API_KEY: "not-a-key" })).toBeNull();
+  });
+
+  test("accepts an unprefixed key when a custom base URL is set", () => {
+    const client = resolveLlmClient(undefined, {
+      ANTHROPIC_API_KEY: "gateway-token",
+      ANTHROPIC_BASE_URL: "https://gateway.internal/v1",
+    });
+
+    expect(client?.provider).toBe("anthropic");
+  });
 });