@kidsinai/kids-client 0.0.9 → 0.0.11

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "type": "module",
   "description": "Own-client TUI for Kids OpenCode — talks to local `opencode serve` via @opencode-ai/sdk v2 with kid-warm rendering, mission progress, permission dialog, and stderr-tail audit pipeline.",
   "license": "MIT",

package/src/core/connection.ts

@@ -13,10 +13,17 @@ export type OpencodeClient = ReturnType<typeof createOpencodeClient>
 export interface ConnectionOptions {
   baseUrl: string
   serverPassword: string
+  /**
+   * Must match upstream's `OPENCODE_SERVER_USERNAME` (default "opencode").
+   * Sending an empty username here yields a 401 against opencode ≥1.x —
+   * see opencode-kernel server/auth.ts `authorized()` which requires
+   * `credentials.username === config.username`.
+   */
+  serverUsername: string
 }
 
 export function createKidsClient(opts: ConnectionOptions): OpencodeClient {
-  const authHeader = "Basic " + btoa(`:${opts.serverPassword}`)
+  const authHeader = buildAuthHeader(opts.serverUsername, opts.serverPassword)
   return createOpencodeClient({
     baseUrl: opts.baseUrl,
     headers: {
@@ -24,3 +31,13 @@ export function createKidsClient(opts: ConnectionOptions): OpencodeClient {
     },
   } as Parameters<typeof createOpencodeClient>[0])
 }
+
+/**
+ * Construct the HTTP Basic-Auth header opencode serve expects.
+ * Exposed so serve-manager's probe + tests can share the exact format
+ * upstream `authorized()` checks against (username MUST match config,
+ * default "opencode" — empty username produces 401 on opencode ≥1.x).
+ */
+export function buildAuthHeader(username: string, password: string): string {
+  return "Basic " + btoa(`${username}:${password}`)
+}

package/src/core/env.ts

@@ -14,6 +14,13 @@ export interface KidsClientEnv {
   opencodeBaseUrl: string
   /** HTTP Basic Auth password for serve. Mandatory. */
   opencodeServerPassword: string
+  /**
+   * HTTP Basic Auth *username* for serve. Defaults to "opencode" to match
+   * upstream's `OPENCODE_SERVER_USERNAME` default (opencode-kernel
+   * packages/opencode/src/server/auth.ts) — sending an empty username here
+   * causes a 401 against opencode ≥1.x even when the password is correct.
+   */
+  opencodeServerUsername: string
   /** DeepRouter tenant key. May be empty when using BYOK bypass. */
   deeprouterApiKey: string
   /** True if the wrapper set KIDS_LLM_BYPASS_GATEWAY=1 (BYOK dogfood mode). */
@@ -39,6 +46,7 @@ export function readEnv(): KidsClientEnv {
   return {
     opencodeBaseUrl: process.env.OPENCODE_BASE_URL ?? "http://127.0.0.1:4096",
     opencodeServerPassword: password,
+    opencodeServerUsername: process.env.OPENCODE_SERVER_USERNAME || "opencode",
     deeprouterApiKey: process.env.DEEPROUTER_API_KEY ?? "",
     bypassGateway: process.env.KIDS_LLM_BYPASS_GATEWAY === "1",
     coursePack: process.env.KIDS_COURSE_PACK || null,

package/src/core/serve-manager.ts

@@ -10,15 +10,36 @@
  */
 
 import { spawn, type Subprocess } from "bun"
+import { buildAuthHeader } from "./connection.ts"
 
 export type ServeReadiness =
   | { kind: "already_running" }
   | { kind: "spawned"; pid: number }
+  // Someone else is holding the port (TCP accepts) but our password doesn't
+  // unlock /app. Usually a stale `opencode serve` from a previous run with a
+  // different OPENCODE_SERVER_PASSWORD. Telling the kid to retry won't help —
+  // they need to free the port (`kids-opencode --shutdown`).
+  | { kind: "port_taken_auth_mismatch"; port: string }
+  // We spawned a child but it exited before becoming ready (e.g. EADDRINUSE,
+  // missing config). exitCode/stderr surface the real cause instead of
+  // making the kid wait 10s for a generic timeout.
+  | { kind: "spawn_failed"; exitCode: number | null; stderrTail: string }
   | { kind: "timeout"; lastError: string }
 
+/** Tri-state probe result; lets ensureReady() distinguish "nobody home"
+ *  from "someone's home but won't let me in". */
+export type ProbeResult = "ok" | "auth_mismatch" | "offline"
+
 export interface ServeManagerOptions {
   baseUrl: string
   serverPassword: string
+  /**
+   * Must match upstream's `OPENCODE_SERVER_USERNAME` (default "opencode").
+   * The probe sends this as the Basic-auth username — upstream's
+   * authorized() requires an exact match, so an empty username produces
+   * a 401 even when the password is correct.
+   */
+  serverUsername: string
   opencodeBin: string
   /** Max wait for readiness probe in ms. Default 10s. */
   readyTimeoutMs?: number
@@ -31,17 +52,30 @@ export interface ServeManagerOptions {
 export class ServeManager {
   private child: Subprocess | null = null
   private opts: ServeManagerOptions
+  // Recent stderr lines from the spawned child, used for spawn_failed
+  // diagnostics. Bounded so it doesn't grow unbounded over a long session.
+  private stderrTail: string[] = []
+  private static STDERR_TAIL_MAX = 20
 
   constructor(opts: ServeManagerOptions) {
     this.opts = opts
   }
 
   /**
-   * Probe baseUrl. If already up, no-op. Otherwise spawn `opencode serve`
-   * as a child, hook stderr parsing, poll until /app responds 200.
+   * Probe baseUrl. If already up, no-op. If something else holds the port
+   * with a different password, return port_taken_auth_mismatch (don't try
+   * to spawn — bind would just fail with EADDRINUSE). Otherwise spawn
+   * `opencode serve`, hook stderr parsing, and race the readiness poll
+   * against the child's exit so port conflicts surface in <1s instead of
+   * timing out after 10s.
    */
   async ensureReady(): Promise<ServeReadiness> {
-    if (await this.probe()) return { kind: "already_running" }
+    const initial = await this.probe()
+    if (initial === "ok") return { kind: "already_running" }
+    if (initial === "auth_mismatch") {
+      const url = new URL(this.opts.baseUrl)
+      return { kind: "port_taken_auth_mismatch", port: url.port || "4096" }
+    }
 
     const url = new URL(this.opts.baseUrl)
     const proc = spawn({
@@ -49,6 +83,7 @@ export class ServeManager {
       env: {
         ...process.env,
         OPENCODE_SERVER_PASSWORD: this.opts.serverPassword,
+        OPENCODE_SERVER_USERNAME: this.opts.serverUsername,
       },
       stdout: "pipe",
       stderr: "pipe",
@@ -61,9 +96,19 @@ export class ServeManager {
     const start = Date.now()
     let lastError = "no response"
     while (Date.now() - start < timeout) {
-      if (await this.probe()) return { kind: "spawned", pid: proc.pid ?? -1 }
+      // If the child died on its own (bind failure, bad args), don't keep
+      // polling — surface the exit immediately with whatever stderr we got.
+      if (proc.exitCode !== null) {
+        return {
+          kind: "spawn_failed",
+          exitCode: proc.exitCode,
+          stderrTail: this.stderrTail.join("\n"),
+        }
+      }
+      const status = await this.probe()
+      if (status === "ok") return { kind: "spawned", pid: proc.pid ?? -1 }
       await new Promise((r) => setTimeout(r, 200))
-      lastError = "still booting"
+      lastError = status === "auth_mismatch" ? "auth mismatch on /app" : "still booting"
     }
     return { kind: "timeout", lastError }
   }
@@ -77,17 +122,20 @@ export class ServeManager {
     this.child = null
   }
 
-  /** GET /app with Basic Auth. Returns true on 200. */
-  private async probe(): Promise<boolean> {
+  /** GET /app with Basic Auth.
+   *  200 → "ok"; 401/403 → "auth_mismatch" (port owned by another instance
+   *  whose password differs); anything else (network refused, 5xx, timeout)
+   *  → "offline". */
+  private async probe(): Promise<ProbeResult> {
     try {
       const res = await fetch(`${this.opts.baseUrl}/app`, {
         headers: {
-          authorization: "Basic " + btoa(`:${this.opts.serverPassword}`),
+          authorization: buildAuthHeader(this.opts.serverUsername, this.opts.serverPassword),
         },
       })
-      return res.ok
+      return classifyProbeStatus(res.status)
     } catch {
-      return false
+      return "offline"
     }
   }
 
@@ -112,11 +160,24 @@ export class ServeManager {
   private handleLine(line: string): void {
     if (!line) return
     const audit = parseAuditLine(line)
-    if (audit) this.opts.onAuditLine?.(audit)
-    else this.opts.onDebugLine?.(line)
+    if (audit) {
+      this.opts.onAuditLine?.(audit)
+      return
+    }
+    this.stderrTail.push(line)
+    if (this.stderrTail.length > ServeManager.STDERR_TAIL_MAX) {
+      this.stderrTail.shift()
+    }
+    this.opts.onDebugLine?.(line)
   }
 }
 
+export function classifyProbeStatus(status: number): ProbeResult {
+  if (status >= 200 && status < 300) return "ok"
+  if (status === 401 || status === 403) return "auth_mismatch"
+  return "offline"
+}
+
 export function parseAuditLine(line: string): unknown | null {
   const prefixes = ["[kids-audit] ", "[kids-tui-audit] "]
   for (const prefix of prefixes) {

package/src/core/store.ts

@@ -28,6 +28,7 @@ export type Screen =
 
 export type ErrorVariant =
   | "serve_unreachable"
+  | "port_taken"
   | "network_down"
   | "stars_exhausted"
   | "auth_failed"

package/src/index.tsx

@@ -64,6 +64,7 @@ interface AppHandlers {
   onPermissionReply: (decision: "allow" | "deny" | "edit") => void
   onDangerousAcknowledge: () => void
   onErrorRetry: () => void | Promise<void>
+  onReconfigure: () => void
   onQuit: () => void | Promise<void>
   onAbort: () => void
   onHelpBack: () => void
@@ -189,6 +190,12 @@ function makeHandlers(
       // Pre-boot error retry: re-run main isn't trivial; just exit.
       process.exit(1)
     },
+    onReconfigure: () => {
+      // From an error screen, jump into the setup wizard so the parent can
+      // change provider / paste a new API key. onSetupContinue knows whether
+      // we're in first-run (resolve gate) or post-boot (reload env + retry).
+      store.update({ screen: { kind: "setup" } })
+    },
     onQuit: async () => {
       const s = servicesHolder.current
       if (s) return s.quit()
@@ -211,6 +218,16 @@ function makeHandlers(
     onSetupContinue: async () => {
       const r = getResolveSetup()
       if (r) r()
+      // Post-boot reconfigure path: services are already up but the env they
+      // were booted with is stale. Re-source the env file (the wizard wrote
+      // it) and replay the same recovery as [Enter] Retry on the error
+      // screen — push the loading screen and re-run readiness probe.
+      const s = servicesHolder.current
+      if (s) {
+        reloadEnvFile(env.configDir)
+        Object.assign(env, readEnv())
+        await s.handlers.onErrorRetry()
+      }
     },
     onSetupSkip: () => {
       const r = getResolveSetup()
@@ -245,6 +262,7 @@ async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSe
   const serve = new ServeManager({
     baseUrl: env.opencodeBaseUrl,
     serverPassword: env.opencodeServerPassword,
+    serverUsername: env.opencodeServerUsername,
     opencodeBin: env.opencodeBin,
     onAuditLine: (event) => {
       audit.push(event)
@@ -254,6 +272,26 @@ async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSe
   })
 
   const readiness = await serve.ensureReady()
+  if (readiness.kind === "port_taken_auth_mismatch") {
+    store.update({
+      screen: {
+        kind: "error",
+        variant: "port_taken",
+        detail: `port ${readiness.port} held by another opencode serve`,
+      },
+    })
+    return null
+  }
+  if (readiness.kind === "spawn_failed") {
+    store.update({
+      screen: {
+        kind: "error",
+        variant: "serve_unreachable",
+        detail: `opencode serve exited (${readiness.exitCode}): ${readiness.stderrTail || "no stderr"}`,
+      },
+    })
+    return null
+  }
   if (readiness.kind === "timeout") {
     store.update({ screen: { kind: "error", variant: "serve_unreachable", detail: readiness.lastError } })
     return null
@@ -262,6 +300,7 @@ async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSe
   const client = createKidsClient({
     baseUrl: env.opencodeBaseUrl,
     serverPassword: env.opencodeServerPassword,
+    serverUsername: env.opencodeServerUsername,
   })
   const session = new SessionManager(client)
 
@@ -491,7 +530,23 @@ function makeFullHandlers(
         },
       })
       const again = await serve.ensureReady()
-      if (again.kind === "timeout") {
+      if (again.kind === "port_taken_auth_mismatch") {
+        store.update({
+          screen: {
+            kind: "error",
+            variant: "port_taken",
+            detail: `port ${again.port} held by another opencode serve`,
+          },
+        })
+      } else if (again.kind === "spawn_failed") {
+        store.update({
+          screen: {
+            kind: "error",
+            variant: "serve_unreachable",
+            detail: `opencode serve exited (${again.exitCode}): ${again.stderrTail || "no stderr"}`,
+          },
+        })
+      } else if (again.kind === "timeout") {
         store.update({ screen: { kind: "error", variant: "serve_unreachable", detail: again.lastError } })
       } else {
         store.update({ screen: { kind: "startup" } })

package/src/render/ink/App.tsx

@@ -11,7 +11,7 @@
 
 import React, { useSyncExternalStore } from "react"
 import type { InstalledPack } from "../../core/course-pack.ts"
-import type { Store } from "../../core/store.ts"
+import type { ErrorVariant, Store } from "../../core/store.ts"
 import { StartupScreen } from "./screens/StartupScreen.tsx"
 import { MissionScreen } from "./screens/MissionScreen.tsx"
 import { PermissionModal } from "./screens/PermissionModal.tsx"
@@ -25,6 +25,17 @@ import { SetupScreen } from "./screens/SetupScreen.tsx"
 import { TourScreen } from "./screens/TourScreen.tsx"
 import type { ProviderId } from "../../core/setup.ts"
 
+// Variants where the root cause may be a stale / wrong API key or a missing
+// provider config — showing a [c] Change settings option that opens the setup
+// wizard actually helps. Pure runtime/network problems (network_down,
+// stars_exhausted, ai_hung) are excluded; they need a different recovery.
+const RECONFIGURABLE_VARIANTS: ReadonlySet<ErrorVariant> = new Set([
+  "serve_unreachable",
+  "port_taken",
+  "auth_failed",
+  "config_missing",
+])
+
 export interface AppDeps {
   store: Store
   locale: "zh-Hans" | "en"
@@ -34,6 +45,11 @@ export interface AppDeps {
   onPermissionReply: (decision: "allow" | "deny" | "edit") => void
   onDangerousAcknowledge: () => void
   onErrorRetry: () => void
+  /**
+   * Jump from the error screen into the setup wizard. Only wired for
+   * config-related variants — see RECONFIGURABLE_VARIANTS below.
+   */
+  onReconfigure: () => void
   onQuit: () => void
   onAbort: () => void
   onHelpBack: () => void
@@ -117,6 +133,7 @@ export function App(deps: AppDeps): React.ReactElement {
           detail={state.screen.detail}
           locale={deps.locale}
           onRetry={deps.onErrorRetry}
+          onReconfigure={RECONFIGURABLE_VARIANTS.has(state.screen.variant) ? deps.onReconfigure : undefined}
           onQuit={deps.onQuit}
         />
       )

package/src/render/ink/screens/ErrorScreen.tsx

@@ -21,12 +21,20 @@ interface ErrorScreenProps {
   detail?: string
   onRetry?: () => void
   onQuit?: () => void
+  /**
+   * Open the setup wizard so the parent can change provider / paste a new
+   * API key. Wired by AppDeps only for config-related variants
+   * (serve_unreachable / port_taken / auth_failed / config_missing) — retry
+   * alone won't fix a wrong key.
+   */
+  onReconfigure?: () => void
 }
 
-export function ErrorScreen({ variant, locale, detail, onRetry, onQuit }: ErrorScreenProps): React.ReactElement {
+export function ErrorScreen({ variant, locale, detail, onRetry, onQuit, onReconfigure }: ErrorScreenProps): React.ReactElement {
   const theme = getTheme()
   useInput((input, key) => {
     if (key.return && onRetry) onRetry()
+    else if ((input === "c" || input === "C") && onReconfigure) onReconfigure()
     else if (input === "q" && onQuit) onQuit()
   })
   const t = STRINGS[locale][variant]
@@ -52,6 +60,12 @@ export function ErrorScreen({ variant, locale, detail, onRetry, onQuit }: ErrorS
             <Text color={theme.fg}> {t.retry}</Text>
           </Box>
         )}
+        {onReconfigure && (
+          <Box marginRight={2}>
+            <Text color={theme.accent}>[c]</Text>
+            <Text color={theme.fg}> {STRINGS[locale].reconfigure}</Text>
+          </Box>
+        )}
         {onQuit && (
           <Box>
             <Text color={theme.accent}>[q]</Text>
@@ -66,11 +80,17 @@ export function ErrorScreen({ variant, locale, detail, onRetry, onQuit }: ErrorS
 const STRINGS = {
   "zh-Hans": {
     quit: "退出",
+    reconfigure: "改设置（换 key / 换 provider）",
     serve_unreachable: {
       title: "AI 老师还没起来",
       body: "后台 AI 服务好像没启动。要不要再试一次？",
       retry: "重试",
     },
+    port_taken: {
+      title: "另一个 AI 老师还在占着位子",
+      body: "请家长打开终端，跑一下：\n\n  kids-opencode --shutdown\n\n然后按 Enter 再试。",
+      retry: "已经关掉了，再试",
+    },
     network_down: {
       title: "网络有点问题",
       body: "我没办法连上 AI。等会儿再来，或者问家长检查网络。",
@@ -99,11 +119,17 @@ const STRINGS = {
   },
   en: {
     quit: "Quit",
+    reconfigure: "Change settings (switch key / provider)",
     serve_unreachable: {
       title: "AI teacher didn't start",
       body: "The background AI service isn't running. Try again?",
       retry: "Retry",
     },
+    port_taken: {
+      title: "Another AI teacher is still holding the seat",
+      body: "Ask a parent to open a terminal and run:\n\n  kids-opencode --shutdown\n\nThen press Enter to try again.",
+      retry: "Done — try again",
+    },
     network_down: {
       title: "Network trouble",
       body: "I can't reach the AI. Try later, or ask an adult to check the connection.",