@kidsinai/kids-client 0.0.5 → 0.0.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "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/store.ts

@@ -10,6 +10,7 @@
 export type Screen =
   | { kind: "loading"; message?: string }
   | { kind: "setup" }
+  | { kind: "tour" }
   | { kind: "startup" }
   | { kind: "mission" }
   | { kind: "help" }

package/src/core/tour-marker.ts

@@ -0,0 +1,27 @@
+/**
+ * First-run welcome-tour marker. File existence at
+ * `<configDir>/tour-seen` means the kid has been through the intro at
+ * least once; the next launch goes straight to StartupScreen.
+ *
+ * The tour only fires when (a) marker absent AND (b) the SetupScreen
+ * just ran. Returning users who inherited env vars skip it.
+ */
+
+import { existsSync, writeFileSync, chmodSync } from "node:fs"
+import { join } from "node:path"
+
+const FILE_NAME = "tour-seen"
+
+export function hasSeenTour(configDir: string): boolean {
+  return existsSync(join(configDir, FILE_NAME))
+}
+
+export function markTourSeen(configDir: string): void {
+  const path = join(configDir, FILE_NAME)
+  try {
+    writeFileSync(path, new Date().toISOString() + "\n", "utf8")
+    chmodSync(path, 0o600)
+  } catch {
+    /* non-fatal — re-show is a feature, not a bug */
+  }
+}

package/src/index.tsx

@@ -34,6 +34,7 @@ import { App } from "./render/ink/App.tsx"
 import { detectDangerousTopicEn, detectDangerousTopicZh } from "./dangerous-topic-bridge.ts"
 import { OAUTH_HANDOFF_EXIT_CODE, saveSetup, saveSetupOauth, type ProviderId } from "./core/setup.ts"
 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"
 
@@ -74,6 +75,7 @@ interface AppHandlers {
   onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
   onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
+  onTourDone: () => void
 }
 
 async function main(): Promise<void> {
@@ -98,17 +100,24 @@ async function main(): Promise<void> {
   let resolveSetup: (() => void) | null = null
   const setupGate = new Promise<void>((r) => { resolveSetup = r })
 
+  // Same pattern for the first-run welcome tour. Only awaited if we actually
+  // route to it (returning users with valid env skip both setup and tour).
+  let resolveTour: (() => void) | null = null
+  const tourGate = new Promise<void>((r) => { resolveTour = r })
+
   const handlers: AppHandlers = makeHandlers(store, env, servicesHolder, resolveSetupFn => {
     resolveSetup = resolveSetupFn
-  }, () => resolveSetup)
+  }, () => resolveSetup, () => resolveTour)
 
   renderApp(store, env, installedPacks, handlers)
 
   // First validation pass.
   let check = validateEnv(env)
+  let didSetup = false
   if (!check.ok && check.variant === "needs_setup") {
     store.update({ screen: { kind: "setup" } })
     await setupGate
+    didSetup = true
 
     // Re-source env file (the setup wizard wrote it).
     reloadEnvFile(env.configDir)
@@ -122,6 +131,14 @@ async function main(): Promise<void> {
     return
   }
 
+  // First-run tour: only fires if the kid just went through setup AND hasn't
+  // seen the tour. Returning users with inherited env vars skip it entirely.
+  if (didSetup && !hasSeenTour(env.configDir)) {
+    store.update({ screen: { kind: "tour" } })
+    await tourGate
+    markTourSeen(env.configDir)
+  }
+
   // Bootstrap services in-process. Loading screen is shown while we wait.
   store.update({
     screen: {
@@ -153,6 +170,7 @@ function makeHandlers(
   servicesHolder: { current: ServiceSet | null },
   _setResolveSetup: (fn: (() => void) | null) => void,
   getResolveSetup: () => (() => void) | null,
+  getResolveTour: () => (() => void) | null,
 ): AppHandlers {
   const ifBooted = <A extends unknown[]>(fn: (s: ServiceSet, ...args: A) => unknown) => (...args: A) => {
     const s = servicesHolder.current
@@ -209,6 +227,10 @@ function makeHandlers(
       // `opencode auth login --provider <p>` interactively, then re-exec us.
       process.exit(OAUTH_HANDOFF_EXIT_CODE)
     },
+    onTourDone: () => {
+      const r = getResolveTour()
+      if (r) r()
+    },
   }
 }
 
@@ -286,7 +308,8 @@ async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSe
       })
     },
     onLlmError: (e) => {
-      store.update({ thinking: false, screen: { kind: "error", variant: "network_down", detail: e.message } })
+      const variant = classifyLlmError(e.message)
+      store.update({ thinking: false, screen: { kind: "error", variant, detail: e.message } })
     },
     onCompactionEnded: () => {
       flashToast(store, {
@@ -560,7 +583,38 @@ function handlePluginAudit(event: unknown, store: Store): void {
     const snap = store.getSnapshot()
     const newBalance = Math.max(0, snap.starsBalance - e.stars_charged)
     store.update({ starsBalance: newBalance })
+    // Preemptive switch the moment the balance lands at zero — kid sees the
+    // friendly "out of stars" screen before the next tool call fails server-side.
+    if (newBalance === 0 && snap.starsBudget > 0 && snap.screen.kind === "mission") {
+      store.update({
+        screen: { kind: "error", variant: "stars_exhausted" },
+        thinking: false,
+      })
+    }
+  }
+}
+
+/**
+ * Pattern-match the LLM/plugin error message against known billing failures
+ * so the kid lands on the friendly "out of stars" screen instead of the
+ * generic "network down" one. The plugin / DeepRouter wraps these with
+ * codes like WALLET_INSUFFICIENT / FAMILY_PAUSED (platform-backend §7) or
+ * plain English ("insufficient credits", "rate limit", "402").
+ */
+function classifyLlmError(msg: string): "stars_exhausted" | "network_down" {
+  const m = msg.toLowerCase()
+  if (
+    m.includes("wallet_insufficient")
+    || m.includes("family_paused")
+    || m.includes("insufficient")
+    || m.includes("out of credit")
+    || m.includes("out of stars")
+    || m.includes("quota")
+    || m.includes("402")
+  ) {
+    return "stars_exhausted"
   }
+  return "network_down"
 }
 
 const TOAST_TTL_MS = 3500

package/src/render/ink/App.tsx

@@ -22,6 +22,7 @@ import { CoursePackPicker } from "./screens/CoursePackPicker.tsx"
 import { MissionCompleteScreen } from "./screens/MissionCompleteScreen.tsx"
 import { LoadingScreen } from "./screens/LoadingScreen.tsx"
 import { SetupScreen } from "./screens/SetupScreen.tsx"
+import { TourScreen } from "./screens/TourScreen.tsx"
 import type { ProviderId } from "../../core/setup.ts"
 
 export interface AppDeps {
@@ -44,6 +45,7 @@ export interface AppDeps {
   onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
   onSetupOAuthHandoff: (provider: ProviderId) => Promise<void>
+  onTourDone: () => void
 }
 
 export function App(deps: AppDeps): React.ReactElement {
@@ -77,6 +79,8 @@ export function App(deps: AppDeps): React.ReactElement {
       return <LoadingScreen locale={deps.locale} message={state.screen.message} />
     case "setup":
       return <SetupScreen locale={deps.locale} onSave={deps.onSetupSave} onContinue={deps.onSetupContinue} onSkip={deps.onSetupSkip} onOAuthHandoff={deps.onSetupOAuthHandoff} />
+    case "tour":
+      return <TourScreen locale={deps.locale} onDone={deps.onTourDone} />
     case "startup":
       return <StartupScreen locale={deps.locale} coursePack={state.coursePack} onStart={deps.onStart} />
     case "mission":

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

@@ -78,8 +78,8 @@ const STRINGS = {
     },
     stars_exhausted: {
       title: "今天的 ⭐ 用完了",
-      body: "明天再来，或者请家长在 airbotix.ai/portal/wallet 充值。",
-      retry: "重试",
+      body: "今天先到这里啦！\n你做得很好，我们明天接着来。\n或者找家长打开 airbotix.ai/portal/wallet 多充一点 ⭐，然后按 Enter 接着做。",
+      retry: "找完家长了，再试一次",
     },
     auth_failed: {
       title: "AI 老师认不出你",
@@ -111,8 +111,8 @@ const STRINGS = {
     },
     stars_exhausted: {
       title: "Out of ⭐ for today",
-      body: "Come back tomorrow, or ask a parent to top up at airbotix.ai/portal/wallet.",
-      retry: "Retry",
+      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.",
+      retry: "Asked a parent — try again",
     },
     auth_failed: {
       title: "AI doesn't recognise you",

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

@@ -7,6 +7,11 @@
  * e → close modal, send a fresh kid prompt of the form "no, do it differently"
  *
  * The PRD uses "y/n/e" to avoid the engineering-vibes of allow/deny.
+ *
+ * For write/edit tools we now render a short preview of the exact file
+ * change the kid is about to approve. Black-box `y` was a trust-without-
+ * verify hole — this closes it AND doubles as a learning surface (the kid
+ * sees what code the AI is producing).
  */
 
 import React from "react"
@@ -22,6 +27,8 @@ interface PermissionModalProps {
   onEdit: () => void
 }
 
+const DIFF_MAX_LINES = 14
+
 export function PermissionModal({ permission, locale, onAllow, onDeny, onEdit }: PermissionModalProps): React.ReactElement {
   const theme = getTheme()
   useInput((input) => {
@@ -31,6 +38,7 @@ export function PermissionModal({ permission, locale, onAllow, onDeny, onEdit }:
     else if (ch === "e") onEdit()
   })
   const t = STRINGS[locale]
+  const preview = extractFilePreview(permission)
   return (
     <Box flexDirection="column" borderStyle="double" borderColor={theme.warn} paddingX={2} paddingY={1}>
       <Text color={theme.warn} bold>{t.title}</Text>
@@ -42,6 +50,22 @@ export function PermissionModal({ permission, locale, onAllow, onDeny, onEdit }:
           <Text color={theme.fgDim}>tool: {permission.tool}</Text>
         </Box>
       )}
+      {preview && (
+        <Box marginTop={1} flexDirection="column" borderStyle="single" borderColor={theme.fgDim} paddingX={1}>
+          <Box>
+            <Text color={theme.accent} bold>{preview.kind === "edit" ? t.editingFile : t.writingFile}: </Text>
+            <Text color={theme.fg}>{preview.path}</Text>
+          </Box>
+          <Box marginTop={1} flexDirection="column">
+            {renderDiffLines(preview, theme)}
+          </Box>
+          {preview.truncated > 0 && (
+            <Box marginTop={1}>
+              <Text color={theme.fgDim} dimColor>{t.truncated(preview.truncated)}</Text>
+            </Box>
+          )}
+        </Box>
+      )}
       {permission.starsEstimated && permission.starsEstimated > 0 && (
         <Box marginTop={1}>
           <Text color={theme.stars}>{t.starsCost(permission.starsEstimated)}</Text>
@@ -59,6 +83,82 @@ export function PermissionModal({ permission, locale, onAllow, onDeny, onEdit }:
   )
 }
 
+type FilePreview =
+  | {
+      kind: "write"
+      path: string
+      lines: string[]
+      truncated: number
+    }
+  | {
+      kind: "edit"
+      path: string
+      removed: string[]
+      added: string[]
+      truncated: number
+    }
+
+/**
+ * opencode write tool metadata: { filePath/path, content }
+ * opencode edit tool metadata: { filePath/path, oldString/old_text, newString/new_text }
+ * Defensive shape extraction — the SDK exposes these as Record<string, unknown>.
+ */
+function extractFilePreview(permission: PendingPermission): FilePreview | null {
+  if (!permission.tool) return null
+  const tool = permission.tool.toLowerCase()
+  const m = permission.metadata ?? {}
+  const path = pickString(m, ["filePath", "path", "file_path", "filename"])
+  if (!path) return null
+
+  if (tool === "write") {
+    const content = pickString(m, ["content", "text", "newContent", "new_content"])
+    if (content === null) return null
+    const all = content.split("\n")
+    const shown = all.slice(0, DIFF_MAX_LINES)
+    return { kind: "write", path, lines: shown, truncated: Math.max(0, all.length - shown.length) }
+  }
+
+  if (tool === "edit") {
+    const oldStr = pickString(m, ["oldString", "old_string", "oldText", "old_text"]) ?? ""
+    const newStr = pickString(m, ["newString", "new_string", "newText", "new_text"]) ?? ""
+    const removed = oldStr.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === ""))
+    const added = newStr.split("\n").filter((l, i, arr) => !(i === arr.length - 1 && l === ""))
+    const totalLines = removed.length + added.length
+    if (totalLines === 0) return null
+    const half = Math.max(1, Math.floor(DIFF_MAX_LINES / 2))
+    const removedShown = removed.slice(0, half)
+    const addedShown = added.slice(0, DIFF_MAX_LINES - removedShown.length)
+    const truncated = (removed.length - removedShown.length) + (added.length - addedShown.length)
+    return { kind: "edit", path, removed: removedShown, added: addedShown, truncated }
+  }
+
+  return null
+}
+
+function renderDiffLines(preview: FilePreview, theme: ReturnType<typeof getTheme>): React.ReactElement[] {
+  if (preview.kind === "write") {
+    return preview.lines.map((line, i) => (
+      <Text key={`w-${i}`} color={theme.success}>{`+ ${line}`}</Text>
+    ))
+  }
+  const out: React.ReactElement[] = []
+  preview.removed.forEach((line, i) => out.push(
+    <Text key={`r-${i}`} color={theme.danger}>{`- ${line}`}</Text>
+  ))
+  preview.added.forEach((line, i) => out.push(
+    <Text key={`a-${i}`} color={theme.success}>{`+ ${line}`}</Text>
+  ))
+  return out
+}
+
+function pickString(obj: Record<string, unknown>, keys: string[]): string | null {
+  for (const k of keys) {
+    const v = obj[k]
+    if (typeof v === "string") return v
+  }
+  return null
+}
+
 const STRINGS = {
   "zh-Hans": {
     title: "AI 想做这件事",
@@ -66,6 +166,9 @@ const STRINGS = {
     no: "不要",
     edit: "我来改",
     starsCost: (n: number) => `预估消耗 ${n}⭐`,
+    writingFile: "新建文件",
+    editingFile: "改这个文件",
+    truncated: (n: number) => `… 还有 ${n} 行没显示。完整改动会在文件里。`,
   },
   en: {
     title: "The AI wants to do this",
@@ -73,5 +176,8 @@ const STRINGS = {
     no: "Stop",
     edit: "I'll do it",
     starsCost: (n: number) => `Estimated cost: ${n}⭐`,
+    writingFile: "Creating file",
+    editingFile: "Editing file",
+    truncated: (n: number) => `… ${n} more lines not shown. Full change lands in the file.`,
   },
 } as const

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

@@ -0,0 +1,155 @@
+/**
+ * First-run welcome tour — 3 steps between SetupScreen and StartupScreen.
+ *
+ * Triggered exactly once per install (gated by ~/.config/kids-opencode/tour-seen).
+ * A returning kid who already has env vars set skips this entirely; only
+ * fires when the wizard just ran. Skip ([s]) marks-seen the same as Done.
+ *
+ * Step content maps to the three things a 12-yo first-timer needs to know
+ * before they look at the StartupScreen and freeze:
+ *   1. What is a Course Pack?
+ *   2. How do I talk to the AI?
+ *   3. What do y / n / e mean when the AI asks permission?
+ */
+
+import React, { useState } from "react"
+import { Box, Text, useInput } from "ink"
+import { getTheme } from "../theme.ts"
+import { KidsLogo } from "../components/KidsLogo.tsx"
+
+interface TourScreenProps {
+  locale: "zh-Hans" | "en"
+  onDone: () => void
+}
+
+export function TourScreen({ locale, onDone }: TourScreenProps): React.ReactElement {
+  const theme = getTheme()
+  const t = STRINGS[locale]
+  const [step, setStep] = useState(0)
+  const last = t.steps.length - 1
+
+  useInput((input, key) => {
+    if (input === "s" || input === "S") {
+      onDone()
+      return
+    }
+    if (key.return || key.rightArrow) {
+      if (step >= last) onDone()
+      else setStep((s) => Math.min(last, s + 1))
+      return
+    }
+    if (key.leftArrow) {
+      setStep((s) => Math.max(0, s - 1))
+    }
+  })
+
+  const current = t.steps[step]!
+  const isLast = step === last
+
+  return (
+    <Box flexDirection="column" alignItems="center" paddingY={1}>
+      <KidsLogo />
+      <Box marginTop={1}>
+        <Text color={theme.fgDim}>{t.progress(step + 1, t.steps.length)}</Text>
+      </Box>
+      <Box marginTop={1} borderStyle="round" borderColor={theme.accent} paddingX={3} paddingY={1} flexDirection="column" width={68}>
+        <Text color={theme.accent} bold>{current.title}</Text>
+        <Box marginTop={1} flexDirection="column">
+          {current.body.map((line, i) => (
+            <Text key={i} color={theme.fg}>{line}</Text>
+          ))}
+        </Box>
+      </Box>
+      <Box marginTop={2}>
+        <Text color={theme.accent}>{isLast ? t.startNow : t.next}</Text>
+        <Text color={theme.fg}>  ·  </Text>
+        <Text color={theme.fgDim}>{t.skip}</Text>
+      </Box>
+    </Box>
+  )
+}
+
+const STRINGS = {
+  "zh-Hans": {
+    progress: (cur: number, total: number) => `${cur} / ${total}`,
+    next: "[Enter] 下一步  [←] 上一步",
+    startNow: "[Enter] 开始玩  [←] 上一步",
+    skip: "[s] 跳过引导",
+    steps: [
+      {
+        title: "📦  什么是 Course Pack？",
+        body: [
+          "Course Pack 是老师为你设计好的一组小项目。",
+          "比如：「做一个网站介绍你的小狗」、「画一只 AI 恐龙」。",
+          "",
+          "每个 Pack 里有几个 Mission，一步一步带你完成。",
+          "做完一个 Mission，✨ 就解锁下一个。",
+        ],
+      },
+      {
+        title: "💬  怎么跟我说话？",
+        body: [
+          "直接打中文或英文，按 Enter 发给我。比如：",
+          "  「帮我做一个红色按钮」",
+          "  「换一个更可爱的字体」",
+          "",
+          "想验收一关：打 「我做完了」 或 /check",
+          "想叫我停下来：按 Esc",
+        ],
+      },
+      {
+        title: "🔐  y / n / e — 你说了算",
+        body: [
+          "我要动你的文件之前，会先问你。三个按键：",
+          "",
+          "  [y]  可以做  — 我一次操作",
+          "  [n]  不要    — 我会停下来，换个办法",
+          "  [e]  我来改  — 你自己写这一步，告诉我你想怎么做",
+          "",
+          "我永远不会绕过这一步偷偷改文件。",
+        ],
+      },
+    ],
+  },
+  en: {
+    progress: (cur: number, total: number) => `${cur} / ${total}`,
+    next: "[Enter] next  [←] back",
+    startNow: "[Enter] start playing  [←] back",
+    skip: "[s] skip tour",
+    steps: [
+      {
+        title: "📦  What's a Course Pack?",
+        body: [
+          "A Course Pack is a set of small projects a teacher made for you.",
+          "Like: \"Build a website about your dog\" or \"Draw an AI dinosaur\".",
+          "",
+          "Each Pack has a few Missions, walking you through step by step.",
+          "Finish one Mission, ✨ unlock the next.",
+        ],
+      },
+      {
+        title: "💬  How do I talk to you?",
+        body: [
+          "Just type in English or Chinese and press Enter. For example:",
+          "  \"Make me a red button\"",
+          "  \"Use a cuter font\"",
+          "",
+          "To check off a mission: type \"I'm done\" or /check",
+          "To stop me mid-reply: press Esc",
+        ],
+      },
+      {
+        title: "🔐  y / n / e — you're in charge",
+        body: [
+          "Before I touch your files I'll ask you. Three keys:",
+          "",
+          "  [y]  go ahead   — I'll do it once",
+          "  [n]  stop        — I'll back off and try another way",
+          "  [e]  I'll do it  — you write this step and tell me what you want",
+          "",
+          "I'll never sneak past this to change files on my own.",
+        ],
+      },
+    ],
+  },
+} as const