@kidsinai/kids-client 0.0.10 → 0.0.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "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). */
@@ -30,6 +37,12 @@ export interface KidsClientEnv {
   configDir: string
   /** When true, the client renders a "Tony banner" / suppresses interactive prompts (CI). */
   noBanner: boolean
+  /**
+   * Airbotix Portal base URL — used by the [w] Wallet / Top-up shortcut to
+   * deep-link parents into login + Airwallex top-up. Defaults to
+   * https://app.airbotix.ai; staging overrides via AIRBOTIX_PORTAL_URL.
+   */
+  portalBaseUrl: string
 }
 
 export function readEnv(): KidsClientEnv {
@@ -39,6 +52,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,
@@ -47,6 +61,7 @@ export function readEnv(): KidsClientEnv {
     opencodeBin: process.env.OPENCODE_BIN ?? "opencode",
     configDir: process.env.KIDS_OPENCODE_CONFIG_DIR ?? join(homedir(), ".config", "kids-opencode"),
     noBanner: process.env.KIDS_OPENCODE_NO_BANNER === "1",
+    portalBaseUrl: process.env.AIRBOTIX_PORTAL_URL || "https://app.airbotix.ai",
   }
 }
 

package/src/core/serve-manager.ts

@@ -10,6 +10,7 @@
  */
 
 import { spawn, type Subprocess } from "bun"
+import { buildAuthHeader } from "./connection.ts"
 
 export type ServeReadiness =
   | { kind: "already_running" }
@@ -32,6 +33,13 @@ 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
@@ -75,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",
@@ -121,7 +130,7 @@ export class ServeManager {
     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 classifyProbeStatus(res.status)

package/src/core/wallet-link.ts

@@ -0,0 +1,76 @@
+/**
+ * Wallet / login deep-link to Airbotix Portal.
+ *
+ * V0 strategy: open the parent's default browser to portal/wallet?from=cli.
+ * Portal handles auth (login first if no session) and Airwallex hosted card
+ * entry. TUI does not touch card data — PCI scope stays in the browser.
+ *
+ * A stable device-id (random UUID, persisted under configDir) is included
+ * so platform-backend can later correlate top-ups with the local install
+ * for V1 device-link polling. Today portal just logs it.
+ */
+
+import { spawn } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { randomUUID } from "node:crypto"
+
+export const DEFAULT_PORTAL_BASE_URL = "https://app.airbotix.ai"
+
+export function getOrCreateDeviceId(configDir: string): string {
+  const p = join(configDir, "device-id")
+  if (existsSync(p)) {
+    const v = readFileSync(p, "utf8").trim()
+    if (v) return v
+  }
+  mkdirSync(configDir, { recursive: true })
+  const id = randomUUID()
+  writeFileSync(p, id + "\n", { mode: 0o600 })
+  return id
+}
+
+export interface WalletUrlOpts {
+  portalBaseUrl?: string
+  deviceId: string
+  locale?: "zh-Hans" | "en"
+}
+
+export function buildWalletUrl(opts: WalletUrlOpts): string {
+  const base = (opts.portalBaseUrl || DEFAULT_PORTAL_BASE_URL).replace(/\/+$/, "")
+  const params = new URLSearchParams({
+    from: "cli",
+    device: opts.deviceId,
+  })
+  if (opts.locale) params.set("lang", opts.locale)
+  return `${base}/portal/wallet?${params.toString()}`
+}
+
+export type OpenResult = { ok: true } | { ok: false; reason: string }
+
+export function openInBrowser(url: string): OpenResult {
+  const platform = process.platform
+  let cmd: string
+  let args: string[]
+  if (platform === "darwin") {
+    cmd = "open"
+    args = [url]
+  } else if (platform === "win32") {
+    // `start` is a cmd.exe builtin; the empty "" is the window title slot.
+    cmd = "cmd"
+    args = ["/c", "start", "", url]
+  } else {
+    cmd = "xdg-open"
+    args = [url]
+  }
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: "ignore" })
+    child.on("error", () => {
+      // Swallow async spawn errors — TUI already showed a toast saying we
+      // tried, and the parent can copy the URL from the toast as fallback.
+    })
+    child.unref()
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) }
+  }
+}

package/src/index.tsx

@@ -37,6 +37,7 @@ import { reloadEnvFile } from "./core/env-reload.ts"
 import { hasSeenTour, markTourSeen } from "./core/tour-marker.ts"
 import type { InstalledPack } from "./core/course-pack.ts"
 import { loadCoursePack } from "@kidsinai/kids-opencode-plugin"
+import { buildWalletUrl, getOrCreateDeviceId, openInBrowser } from "./core/wallet-link.ts"
 
 interface ServiceSet {
   audit: AuditPipeline
@@ -64,6 +65,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
@@ -76,6 +78,7 @@ interface AppHandlers {
   onSetupSkip: () => void
   onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
   onTourDone: () => void
+  onOpenWallet: () => void
 }
 
 async function main(): Promise<void> {
@@ -189,6 +192,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 +220,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()
@@ -231,6 +250,25 @@ function makeHandlers(
       const r = getResolveTour()
       if (r) r()
     },
+    onOpenWallet: () => {
+      const deviceId = getOrCreateDeviceId(env.configDir)
+      const url = buildWalletUrl({
+        portalBaseUrl: env.portalBaseUrl,
+        deviceId,
+        locale: env.locale,
+      })
+      const result = openInBrowser(url)
+      const okText = env.locale === "zh-Hans"
+        ? `已在浏览器打开：${url}`
+        : `Opened in your browser: ${url}`
+      const failText = env.locale === "zh-Hans"
+        ? `没办法自动开浏览器。请手动打开：${url}`
+        : `Couldn't auto-open the browser. Open manually: ${url}`
+      flashToast(store, {
+        kind: result.ok ? "success" : "warn",
+        text: result.ok ? okText : failText,
+      })
+    },
   }
 }
 
@@ -245,6 +283,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)
@@ -282,6 +321,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)
 

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
@@ -46,6 +62,13 @@ export interface AppDeps {
   onSetupSkip: () => void
   onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
   onTourDone: () => void
+  /**
+   * Open the Airbotix Portal wallet/login page in the parent's default
+   * browser. Wired into [w] on StartupScreen and into the
+   * `stars_exhausted` ErrorScreen so parents can top up without
+   * remembering the URL.
+   */
+  onOpenWallet: () => void
 }
 
 export function App(deps: AppDeps): React.ReactElement {
@@ -82,7 +105,7 @@ export function App(deps: AppDeps): React.ReactElement {
     case "tour":
       return <TourScreen locale={deps.locale} onDone={deps.onTourDone} />
     case "startup":
-      return <StartupScreen locale={deps.locale} coursePack={state.coursePack} onStart={deps.onStart} />
+      return <StartupScreen locale={deps.locale} coursePack={state.coursePack} toast={state.toast} onStart={deps.onStart} onOpenWallet={deps.onOpenWallet} />
     case "mission":
       return <MissionScreen state={state} locale={deps.locale} onPrompt={deps.onPrompt} onAbort={deps.onAbort} />
     case "help":
@@ -116,7 +139,10 @@ export function App(deps: AppDeps): React.ReactElement {
           variant={state.screen.variant}
           detail={state.screen.detail}
           locale={deps.locale}
+          toast={state.toast}
           onRetry={deps.onErrorRetry}
+          onReconfigure={RECONFIGURABLE_VARIANTS.has(state.screen.variant) ? deps.onReconfigure : undefined}
+          onOpenWallet={state.screen.variant === "stars_exhausted" ? deps.onOpenWallet : undefined}
           onQuit={deps.onQuit}
         />
       )

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

@@ -14,19 +14,36 @@ import React from "react"
 import { Box, Text, useInput } from "ink"
 import { getTheme } from "../theme.ts"
 import type { ErrorVariant } from "../../../core/store.ts"
+import { Toast, type ToastState } from "../components/Toast.tsx"
 
 interface ErrorScreenProps {
   variant: ErrorVariant
   locale: "zh-Hans" | "en"
   detail?: string
+  toast?: ToastState | null
   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
+  /**
+   * Open the Airbotix Portal wallet page in the parent's default browser.
+   * Wired only for `stars_exhausted` so retry-alone (which won't change the
+   * balance) is not the only option.
+   */
+  onOpenWallet?: () => void
 }
 
-export function ErrorScreen({ variant, locale, detail, onRetry, onQuit }: ErrorScreenProps): React.ReactElement {
+export function ErrorScreen({ variant, locale, detail, toast, onRetry, onQuit, onReconfigure, onOpenWallet }: 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 === "w" || input === "W") && onOpenWallet) onOpenWallet()
     else if (input === "q" && onQuit) onQuit()
   })
   const t = STRINGS[locale][variant]
@@ -52,6 +69,18 @@ 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>
+        )}
+        {onOpenWallet && (
+          <Box marginRight={2}>
+            <Text color={theme.accent}>[w]</Text>
+            <Text color={theme.fg}> {STRINGS[locale].topUp}</Text>
+          </Box>
+        )}
         {onQuit && (
           <Box>
             <Text color={theme.accent}>[q]</Text>
@@ -59,6 +88,11 @@ export function ErrorScreen({ variant, locale, detail, onRetry, onQuit }: ErrorS
           </Box>
         )}
       </Box>
+      {toast && (
+        <Box marginTop={1}>
+          <Toast toast={toast} />
+        </Box>
+      )}
     </Box>
   )
 }
@@ -66,6 +100,8 @@ export function ErrorScreen({ variant, locale, detail, onRetry, onQuit }: ErrorS
 const STRINGS = {
   "zh-Hans": {
     quit: "退出",
+    reconfigure: "改设置（换 key / 换 provider）",
+    topUp: "去充值（开浏览器）",
     serve_unreachable: {
       title: "AI 老师还没起来",
       body: "后台 AI 服务好像没启动。要不要再试一次？",
@@ -83,7 +119,7 @@ const STRINGS = {
     },
     stars_exhausted: {
       title: "今天的 ⭐ 用完了",
-      body: "今天先到这里啦！\n你做得很好，我们明天接着来。\n或者找家长打开 airbotix.ai/portal/wallet 多充一点 ⭐，然后按 Enter 接着做。",
+      body: "今天先到这里啦！\n你做得很好，我们明天接着来。\n或者按 [w] 让家长去充值，回来按 Enter 接着做。",
       retry: "找完家长了，再试一次",
     },
     auth_failed: {
@@ -104,6 +140,8 @@ const STRINGS = {
   },
   en: {
     quit: "Quit",
+    reconfigure: "Change settings (switch key / provider)",
+    topUp: "Top up (opens browser)",
     serve_unreachable: {
       title: "AI teacher didn't start",
       body: "The background AI service isn't running. Try again?",
@@ -121,7 +159,7 @@ const STRINGS = {
     },
     stars_exhausted: {
       title: "Out of ⭐ for today",
-      body: "Great work today!\nWe'll pick this up tomorrow.\nOr ask a parent to top up at airbotix.ai/portal/wallet, then press Enter to keep going.",
+      body: "Great work today!\nWe'll pick this up tomorrow.\nOr press [w] so a parent can top up, then press Enter to keep going.",
       retry: "Asked a parent — try again",
     },
     auth_failed: {

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

@@ -5,6 +5,7 @@
  *   Enter → start a free-play session OR continue if a course pack is set
  *   c     → choose a Course Pack
  *   r     → resume the last session
+ *   w     → open Airbotix Portal wallet / login in the parent's browser
  *   h     → show kid-friendly help
  */
 
@@ -13,19 +14,23 @@ import { Box, Text, useInput } from "ink"
 import { getTheme } from "../theme.ts"
 import { KidsLogo } from "../components/KidsLogo.tsx"
 import { KeyHints } from "../components/KeyHints.tsx"
+import { Toast, type ToastState } from "../components/Toast.tsx"
 
 interface StartupScreenProps {
   locale: "zh-Hans" | "en"
   coursePack: string | null
+  toast: ToastState | null
   onStart: (mode: "free" | "course" | "resume" | "help") => void
+  onOpenWallet: () => void
 }
 
-export function StartupScreen({ locale, coursePack, onStart }: StartupScreenProps): React.ReactElement {
+export function StartupScreen({ locale, coursePack, toast, onStart, onOpenWallet }: StartupScreenProps): React.ReactElement {
   const theme = getTheme()
   useInput((input, key) => {
     if (key.return) onStart(coursePack ? "course" : "free")
     else if (input === "c") onStart("course")
     else if (input === "r") onStart("resume")
+    else if (input === "w" || input === "W") onOpenWallet()
     else if (input === "h") onStart("help")
   })
   const t = STRINGS[locale]
@@ -51,9 +56,15 @@ export function StartupScreen({ locale, coursePack, onStart }: StartupScreenProp
           { key: "Enter", label: coursePack ? t.startCourse : t.startFree },
           { key: "c", label: t.pickCourse },
           { key: "r", label: t.resume },
+          { key: "w", label: t.wallet },
           { key: "h", label: t.help },
         ]} />
       </Box>
+      {toast && (
+        <Box marginTop={1}>
+          <Toast toast={toast} />
+        </Box>
+      )}
     </Box>
   )
 }
@@ -70,6 +81,7 @@ const STRINGS = {
     startCourse: "继续 Course Pack",
     pickCourse: "选 Course Pack",
     resume: "继续上次",
+    wallet: "钱包 / 充值（开浏览器）",
     help: "帮助",
   },
   en: {
@@ -83,6 +95,7 @@ const STRINGS = {
     startCourse: "Continue Course Pack",
     pickCourse: "Pick a Course Pack",
     resume: "Resume last session",
+    wallet: "Wallet / Top up (opens browser)",
     help: "Help",
   },
 } as const