@kidsinai/kids-client 0.0.18 → 0.0.20

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@kidsinai/kids-client",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "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",
@@ -35,7 +35,7 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "react": "^18.3.1",
-    "@kidsinai/kids-opencode-plugin": "^0.0.18"
+    "@kidsinai/kids-opencode-plugin": "^0.0.20"
   },
   "devDependencies": {
     "@opencode-ai/sdk": "^1.14.51",

package/src/core/commands.ts

@@ -0,0 +1,105 @@
+/**
+ * Kid-safe slash-command registry.
+ *
+ * kids-client is a custom minimal TUI (not opencode's native one), so it grows
+ * its OWN command set rather than exposing opencode's full palette. This module
+ * is pure metadata + parsing — the actual effects live in index.tsx's prompt
+ * dispatcher (it needs the store / session / client). Keeping it pure makes the
+ * list unit-testable and lets MissionScreen render live suggestions.
+ *
+ * Deliberately EXCLUDED for kid-safety: /share (public links), /editor &
+ * drop-to-shell, external @-mentions, arbitrary config edits. The server-side
+ * tool whitelist (kids-plugin system prompt) blocks the dangerous primitives
+ * anyway; we just don't surface the affordances.
+ */
+
+export type Locale = "zh-Hans" | "en"
+
+export interface KidCommand {
+  id: string
+  /** Primary slash form, e.g. "/model". */
+  slash: string
+  /** Extra accepted spellings, e.g. ["/models"]. */
+  aliases?: string[]
+  label: { en: string; zh: string }
+  hint: { en: string; zh: string }
+}
+
+/** Order here is the order shown in the suggestion list / /help. */
+export const COMMANDS: KidCommand[] = [
+  { id: "help", slash: "/help", aliases: ["/?", "/commands"],
+    label: { en: "Help", zh: "帮助" },
+    hint: { en: "Show what you can type", zh: "看看能输入哪些命令" } },
+  { id: "model", slash: "/model", aliases: ["/models"],
+    label: { en: "Pick AI model", zh: "选 AI 模型" },
+    hint: { en: "Choose which AI helps you", zh: "换一个帮你的 AI 模型" } },
+  { id: "sessions", slash: "/sessions", aliases: ["/history", "/chats"],
+    label: { en: "Past chats", zh: "历史对话" },
+    hint: { en: "Open an earlier conversation", zh: "打开之前的对话" } },
+  { id: "new", slash: "/new",
+    label: { en: "New chat", zh: "开新对话" },
+    hint: { en: "Start a fresh conversation", zh: "清空，开始一段新的对话" } },
+  { id: "check", slash: "/check", aliases: ["/done"],
+    label: { en: "Check my work", zh: "验收作品" },
+    hint: { en: "See if you finished the mission", zh: "看看这一关完成没有" } },
+  { id: "clear", slash: "/clear",
+    label: { en: "Clear screen", zh: "清屏" },
+    hint: { en: "Clear the chat (your files stay)", zh: "清空聊天记录（文件不动）" } },
+  { id: "menu", slash: "/menu", aliases: ["/home"],
+    label: { en: "Main menu", zh: "主菜单" },
+    hint: { en: "Back to the start screen", zh: "回到开始界面" } },
+  { id: "quit", slash: "/quit", aliases: ["/exit"],
+    label: { en: "Quit", zh: "退出" },
+    hint: { en: "Close Kids OpenCode", zh: "关闭 Kids OpenCode" } },
+]
+
+export interface ParsedCommand {
+  /** The slash token as typed, lowercased, incl. leading "/", e.g. "/model". */
+  name: string
+  /** Everything after the command word, trimmed (may be ""). */
+  args: string
+}
+
+/** Parse a slash command line. Returns null if `text` isn't a `/command`. */
+export function parseSlash(text: string): ParsedCommand | null {
+  const t = text.trim()
+  if (!t.startsWith("/")) return null
+  const space = t.indexOf(" ")
+  if (space === -1) return { name: t.toLowerCase(), args: "" }
+  return { name: t.slice(0, space).toLowerCase(), args: t.slice(space + 1).trim() }
+}
+
+/** Resolve a parsed command name (e.g. "/models") to its KidCommand. */
+export function matchCommand(name: string): KidCommand | null {
+  const n = name.toLowerCase()
+  for (const c of COMMANDS) {
+    if (c.slash === n) return c
+    if (c.aliases?.includes(n)) return c
+  }
+  return null
+}
+
+/**
+ * Commands matching a draft query (the text the kid has typed so far,
+ * including the leading "/"). "/" alone returns everything. Matches against
+ * slash, aliases, id, and both labels so "/mod" or "/模型"-style typing finds
+ * the model command.
+ */
+export function filterCommands(query: string): KidCommand[] {
+  const q = query.trim().toLowerCase()
+  if (q === "" || q === "/") return COMMANDS
+  return COMMANDS.filter((c) => {
+    const hay = [c.slash, ...(c.aliases ?? []), c.id, c.label.en, c.label.zh]
+      .join(" ")
+      .toLowerCase()
+    return hay.includes(q.replace(/^\//, ""))
+  })
+}
+
+export function commandLabel(c: KidCommand, locale: Locale): string {
+  return locale === "zh-Hans" ? c.label.zh : c.label.en
+}
+
+export function commandHint(c: KidCommand, locale: Locale): string {
+  return locale === "zh-Hans" ? c.hint.zh : c.hint.en
+}

package/src/core/debug.ts

@@ -0,0 +1,51 @@
+/**
+ * Tiny file-based debug logger.
+ *
+ * Always-on writes to ~/.config/kids-opencode/debug.log so we can see what
+ * actually happened in a TUI session after the fact (Ink owns the terminal,
+ * so console.log/error doesn't show on screen and would also break the
+ * alt-screen-buffer canvas).
+ *
+ * Set KIDS_DEBUG=0 to silence it. Otherwise it's on by default while we're
+ * still chasing the "thinking…" hang in dogfood.
+ */
+
+import { appendFileSync, mkdirSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { homedir } from "node:os"
+
+const PATH = process.env.KIDS_DEBUG_LOG
+  ?? join(process.env.KIDS_OPENCODE_CONFIG_DIR ?? join(homedir(), ".config", "kids-opencode"), "debug.log")
+
+const ENABLED = process.env.KIDS_DEBUG !== "0"
+
+let initialised = false
+
+function init(): void {
+  if (initialised) return
+  try {
+    mkdirSync(dirname(PATH), { recursive: true })
+    appendFileSync(PATH, `\n===== kids-client debug log opened at ${new Date().toISOString()} (pid ${process.pid}) =====\n`, "utf8")
+  } catch {
+    // can't init — disable to avoid further failures
+    initialised = true
+    return
+  }
+  initialised = true
+}
+
+export function debug(message: string, fields?: Record<string, unknown>): void {
+  if (!ENABLED) return
+  init()
+  try {
+    const stamp = new Date().toISOString()
+    const tail = fields ? " " + JSON.stringify(fields) : ""
+    appendFileSync(PATH, `${stamp} ${message}${tail}\n`, "utf8")
+  } catch {
+    // best-effort, never throw from the logger
+  }
+}
+
+export function debugLogPath(): string {
+  return PATH
+}

package/src/core/events.ts

@@ -66,6 +66,14 @@ export class EventSubscriber {
     this.abort.abort()
   }
 
+  private dbg(message: string, fields?: Record<string, unknown>): void {
+    // Lazy require to avoid a hard dep cycle if debug.ts grows imports.
+    try {
+      const { debug } = require("./debug.ts") as { debug: (m: string, f?: Record<string, unknown>) => void }
+      debug(`[events] ${message}`, fields)
+    } catch { /* never let logging block events */ }
+  }
+
   private async consume(): Promise<void> {
     // The SDK exposes the SSE stream via client.global.event(). The shape
     // has changed across SDK versions:
@@ -78,79 +86,106 @@ export class EventSubscriber {
     if (!eventApi || typeof eventApi.event !== "function") {
       throw new Error("@opencode-ai/sdk/v2: client.global.event() not available — SDK version drift")
     }
+    this.dbg("consume: calling event()")
     const result = await Promise.resolve(eventApi.event())
+    this.dbg("consume: event() returned", { shape: describeShape(result) })
     const iterable = pickAsyncIterable(result)
     if (!iterable) {
       throw new Error(`@opencode-ai/sdk/v2: client.global.event() returned an unrecognised shape: ${describeShape(result)}`)
     }
+    this.dbg("consume: got iterable, awaiting SSE events…")
     for await (const raw of iterable) {
       if (this.abort.signal.aborted) return
       if (this.retries > 0) {
         this.retries = 0
         this.handlers.onReconnected?.()
       }
+      this.dbg("consume: raw event", { preview: previewRaw(raw) })
       this.dispatch(raw)
     }
+    this.dbg("consume: iterable ended")
   }
 
   private dispatch(raw: unknown): void {
-    // Across SDK versions an event is either:
-    //   • { payload: { type, …fields } }            (older shape)
-    //   • { type, …fields }                          (newer shape — yielded
-    //                                                  directly by the
-    //                                                  AsyncGenerator)
-    //   • { data: { type, …fields } } (StreamEvent wrapper from some helpers)
-    // Unwrap to a single `payload` view so the switch below stays the same.
+    // The SDK shape evolved over the 1.14.x line. Yielded events arrive as:
+    //   • { payload: { type, properties: { … } } }   (current — 1.14.51 GlobalEvent)
+    //   • { payload: { type, …flatfields } }         (older — flat fields on payload)
+    //   • { type, properties: { … } }                (some intermediate releases)
+    //   • { type, …flatfields }                      (oldest)
+    //   • { data: { type, …. } }                     (StreamEvent helper wrapper)
+    //
+    // CRITICAL: the current 1.14.51 GlobalEvent puts event fields
+    // (sessionID, messageID, delta, …) under .payload.properties, NOT
+    // directly on .payload. The previous code read .payload.sessionID
+    // (always undefined), so deltas were silently dropped and the
+    // "thinking" indicator never cleared. This split + the
+    // `props ?? payload` fallback handle both layouts uniformly.
     const e = raw as { payload?: Record<string, unknown>; data?: Record<string, unknown>; type?: string } & Record<string, unknown>
-    const payload: ({ type?: string } & Record<string, unknown>) | null =
-      (e?.payload && typeof e.payload === "object") ? (e.payload as { type?: string } & Record<string, unknown>)
-      : (e?.data && typeof e.data === "object" && typeof (e.data as { type?: unknown }).type === "string") ? (e.data as { type?: string } & Record<string, unknown>)
-      : (typeof e?.type === "string") ? (e as { type?: string } & Record<string, unknown>)
+    const payload: ({ type?: string; properties?: Record<string, unknown> } & Record<string, unknown>) | null =
+      (e?.payload && typeof e.payload === "object") ? (e.payload as { type?: string; properties?: Record<string, unknown> } & Record<string, unknown>)
+      : (e?.data && typeof e.data === "object" && typeof (e.data as { type?: unknown }).type === "string") ? (e.data as { type?: string; properties?: Record<string, unknown> } & Record<string, unknown>)
+      : (typeof e?.type === "string") ? (e as { type?: string; properties?: Record<string, unknown> } & Record<string, unknown>)
       : null
     if (!payload || typeof payload.type !== "string") return
-    const t = payload.type
+    let t = payload.type
+    // Where the actual event fields live: `.properties` (Event* legacy shape)
+    // OR `.data` (SyncEvent* shape) OR flat on payload (oldest).
+    let props: Record<string, unknown> = (payload.properties && typeof payload.properties === "object")
+      ? payload.properties as Record<string, unknown>
+      : payload
+    // 1.14.51 Sync events: type="sync", real event name in .name with a
+    // version suffix like ".1", fields under .data. Without this normalize,
+    // our switch never matches and streaming text events drop on the floor
+    // (kid sees "thinking..." forever).
+    if (t === "sync" && typeof (payload as { name?: unknown }).name === "string") {
+      t = String((payload as { name: string }).name).replace(/\.\d+$/, "")
+      const dataField = (payload as { data?: unknown }).data
+      if (dataField && typeof dataField === "object") {
+        props = dataField as Record<string, unknown>
+      }
+    }
     switch (t) {
       case "session.created":
       case "session.next.session.created":
-        this.handlers.onSessionCreated?.({ sessionID: String(payload.sessionID ?? "") })
+        this.handlers.onSessionCreated?.({ sessionID: String(props.sessionID ?? "") })
         return
       case "message.part.delta": {
-        const messageID = String(payload.messageID ?? "")
-        const partID = String(payload.partID ?? "")
-        const sessionID = String(payload.sessionID ?? "")
-        const delta = String((payload.delta as { text?: string } | undefined)?.text ?? payload.delta ?? "")
+        const messageID = String(props.messageID ?? "")
+        const partID = String(props.partID ?? "")
+        const sessionID = String(props.sessionID ?? "")
+        const delta = String((props.delta as { text?: string } | undefined)?.text ?? props.delta ?? "")
         if (delta) this.handlers.onMessagePartDelta?.({ sessionID, messageID, partID, delta })
         return
       }
       case "session.next.text.delta": {
-        const messageID = String(payload.messageID ?? "")
-        const partID = String(payload.partID ?? "stream")
-        const sessionID = String(payload.sessionID ?? "")
-        const delta = String(payload.delta ?? "")
+        const messageID = String(props.messageID ?? "")
+        const partID = String(props.partID ?? "stream")
+        const sessionID = String(props.sessionID ?? "")
+        const delta = String(props.delta ?? "")
         if (delta) this.handlers.onMessagePartDelta?.({ sessionID, messageID, partID, delta })
         return
       }
       case "session.next.text.ended": {
-        const messageID = String(payload.messageID ?? "")
-        const sessionID = String(payload.sessionID ?? "")
+        const messageID = String(props.messageID ?? "")
+        const sessionID = String(props.sessionID ?? "")
         this.handlers.onTextEnded?.({ sessionID, messageID })
         return
       }
       case "permission.asked":
       case "session.next.permission.asked": {
-        const requestID = String(payload.requestID ?? payload.id ?? "")
-        const sessionID = String(payload.sessionID ?? "")
+        const requestID = String(props.requestID ?? props.id ?? "")
+        const sessionID = String(props.sessionID ?? "")
         this.handlers.onPermissionAsked?.({
           requestID,
           sessionID,
-          tool: payload.tool as string | undefined,
-          metadata: payload.metadata as Record<string, unknown> | undefined,
+          tool: props.tool as string | undefined,
+          metadata: props.metadata as Record<string, unknown> | undefined,
         })
         return
       }
       case "session.error":
       case "llm.error": {
-        const message = String((payload.error as { message?: string } | undefined)?.message ?? payload.message ?? "unknown LLM error")
+        const message = String((props.error as { message?: string } | undefined)?.message ?? props.message ?? "unknown LLM error")
         this.handlers.onLlmError?.({ message })
         return
       }
@@ -217,3 +252,12 @@ function describeShape(value: unknown): string {
   if (typeof value !== "object") return typeof value
   return `object keys=[${Object.keys(value as object).join(",")}]`
 }
+
+function previewRaw(raw: unknown): string {
+  try {
+    const s = JSON.stringify(raw)
+    return s.length > 220 ? s.slice(0, 220) + "…" : s
+  } catch {
+    return describeShape(raw)
+  }
+}

package/src/core/models.ts

@@ -0,0 +1,66 @@
+/**
+ * Flatten the server's provider/model list into kid-friendly choices for the
+ * `/model` picker. Duck-typed and defensive: opencode's provider list shape has
+ * shifted across versions and a missing/!errored endpoint must degrade to an
+ * empty list (the picker shows a friendly "no models" note) rather than crash.
+ */
+
+import type { OpencodeClient } from "./connection.ts"
+import type { ModelChoice } from "./store.ts"
+
+const MAX_MODELS = 40
+
+export async function listModels(client: OpencodeClient): Promise<ModelChoice[]> {
+  const api = client as unknown as {
+    provider?: { list?: () => Promise<unknown> }
+    config?: { providers?: () => Promise<unknown> }
+  }
+  let raw: unknown
+  try {
+    if (typeof api.provider?.list === "function") raw = await api.provider.list()
+    else if (typeof api.config?.providers === "function") raw = await api.config.providers()
+    else return []
+  } catch {
+    return []
+  }
+  return flattenModels(raw).slice(0, MAX_MODELS)
+}
+
+export function flattenModels(raw: unknown): ModelChoice[] {
+  const providers = pickProviders(raw)
+  const out: ModelChoice[] = []
+  const seen = new Set<string>()
+  for (const p of providers) {
+    const prov = p as { id?: string; name?: string; models?: unknown }
+    const pid = prov.id ?? ""
+    const pname = prov.name ?? pid
+    for (const m of pickModels(prov.models)) {
+      const mod = m as { id?: string; name?: string }
+      const mid = mod.id ?? ""
+      if (!pid || !mid) continue
+      const fullId = `${pid}/${mid}`
+      if (seen.has(fullId)) continue
+      seen.add(fullId)
+      const mname = mod.name ?? mid
+      out.push({ id: fullId, label: pname ? `${mname} · ${pname}` : mname })
+    }
+  }
+  return out
+}
+
+function pickProviders(raw: unknown): unknown[] {
+  if (Array.isArray(raw)) return raw
+  if (raw && typeof raw === "object") {
+    const o = raw as { providers?: unknown; data?: { providers?: unknown } }
+    if (Array.isArray(o.providers)) return o.providers
+    if (Array.isArray(o.data?.providers)) return o.data!.providers as unknown[]
+  }
+  return []
+}
+
+function pickModels(models: unknown): unknown[] {
+  if (Array.isArray(models)) return models
+  // Most shapes use a Record<modelId, Model> map.
+  if (models && typeof models === "object") return Object.values(models)
+  return []
+}

package/src/core/session.ts

@@ -10,6 +10,17 @@
  */
 
 import type { OpencodeClient } from "./connection.ts"
+import type { SessionSummary } from "./store.ts"
+import { debug } from "./debug.ts"
+
+/**
+ * SDK 1.14.x default is `ThrowOnError=false` which returns the discriminated
+ * union { data, error }. If we don't inspect `.error`, auth / 4xx / 5xx
+ * responses are silently swallowed and the kid sees "thinking…" forever.
+ * Pass this options object to every call so the SDK throws and the
+ * orchestrator's existing try/catch can surface the error on ErrorScreen.
+ */
+const SDK_THROW: { throwOnError: true } = { throwOnError: true }
 
 export class SessionManager {
   private client: OpencodeClient
@@ -23,36 +34,85 @@ export class SessionManager {
     return this.currentSessionId
   }
 
+  /** Forget the current session so the next prompt() opens a fresh one. */
+  reset(): void {
+    this.currentSessionId = null
+  }
+
+  /** List past sessions (for the `/sessions` picker). Newest-ish first. */
+  async list(): Promise<SessionSummary[]> {
+    const api = (this.client as unknown as { session?: { list?: () => Promise<unknown> } }).session
+    if (!api?.list) return []
+    const raw = await api.list()
+    const arr = unwrapArray(raw)
+    return arr
+      .map((s) => {
+        const o = s as { id?: string; title?: string }
+        if (!o?.id) return null
+        return { id: o.id, title: (o.title ?? "").trim() || o.id }
+      })
+      .filter((s): s is SessionSummary => s !== null)
+  }
+
+  /** Continue an existing session: subsequent prompt()s append to it. */
+  switchTo(sessionID: string): void {
+    this.currentSessionId = sessionID
+  }
+
   async create(): Promise<string> {
-    const api = (this.client as unknown as { session?: { create: (input?: unknown) => Promise<{ data?: { id?: string } } | { id?: string } | string> } }).session
+    const api = (this.client as unknown as { session?: { create: (input?: unknown, options?: unknown) => Promise<{ data?: { id?: string } } | { id?: string } | string> } }).session
     if (!api?.create) throw new Error("SDK v2: client.session.create unavailable")
-    const result = await api.create({})
+    debug("session.create: calling SDK")
+    const result = await api.create({}, SDK_THROW)
+    debug("session.create: result shape", { keys: result && typeof result === "object" ? Object.keys(result) : typeof result })
     const id = extractId(result)
     if (!id) throw new Error("SDK v2 session.create returned no id")
     this.currentSessionId = id
+    debug("session.create: id", { id })
     return id
   }
 
   async prompt(text: string, opts?: { model?: string; agent?: string }): Promise<void> {
     if (!this.currentSessionId) await this.create()
     const sessionID = this.currentSessionId!
-    const api = (this.client as unknown as { session?: { prompt: (sessionID: string, body: unknown) => Promise<unknown> } }).session
+    const api = (this.client as unknown as { session?: { prompt: (parameters: unknown, options?: unknown) => Promise<unknown> } }).session
     if (!api?.prompt) throw new Error("SDK v2: client.session.prompt unavailable")
-    await api.prompt(sessionID, {
-      parts: [{ type: "text", text }],
-      model: opts?.model,
-      agent: opts?.agent,
-    })
+    // SDK 1.14.51 signature: single parameters object, kid's text under .prompt.text.
+    // Pass SDK_THROW so 4xx/5xx surface as exceptions instead of getting
+    // silently swallowed (the bug behind the "thinking…" hang).
+    // `model` (from the /model picker) is a "providerID/modelID" string; the SDK
+    // wants it split into { providerID, modelID }.
+    const model = splitModelId(opts?.model)
+    const payload = {
+      sessionID,
+      prompt: { text },
+      ...(model ? { model } : {}),
+      ...(opts?.agent ? { agent: opts.agent } : {}),
+    }
+    debug("session.prompt: sending", { sessionID, textLen: text.length })
+    try {
+      const result = await api.prompt(payload, SDK_THROW)
+      debug("session.prompt: SDK returned", { keys: result && typeof result === "object" ? Object.keys(result) : typeof result })
+    } catch (err) {
+      debug("session.prompt: SDK threw", { error: errMsg(err) })
+      throw err
+    }
   }
 
   async abort(): Promise<void> {
     if (!this.currentSessionId) return
-    const api = (this.client as unknown as { session?: { abort: (sessionID: string) => Promise<unknown> } }).session
+    const api = (this.client as unknown as { session?: { abort: (parameters: unknown, options?: unknown) => Promise<unknown> } }).session
     if (!api?.abort) return
-    await api.abort(this.currentSessionId)
+    debug("session.abort", { sessionID: this.currentSessionId })
+    await api.abort({ sessionID: this.currentSessionId }, SDK_THROW)
   }
 }
 
+function errMsg(err: unknown): string {
+  if (err instanceof Error) return `${err.name}: ${err.message}`
+  try { return JSON.stringify(err) } catch { return String(err) }
+}
+
 function extractId(result: unknown): string | null {
   if (typeof result === "string") return result
   if (result && typeof result === "object") {
@@ -61,3 +121,25 @@ function extractId(result: unknown): string | null {
   }
   return null
 }
+
+/**
+ * Split a "providerID/modelID" id (as built by the /model picker) into the
+ * shape the SDK prompt body wants. Splits on the FIRST slash so model ids that
+ * themselves contain "/" survive. Returns undefined for empty/no input.
+ */
+function splitModelId(id: string | undefined): { providerID: string; modelID: string } | undefined {
+  if (!id) return undefined
+  const slash = id.indexOf("/")
+  if (slash <= 0 || slash === id.length - 1) return undefined
+  return { providerID: id.slice(0, slash), modelID: id.slice(slash + 1) }
+}
+
+/** SDK list responses come back as `T[]` or `{ data: T[] }` across versions. */
+function unwrapArray(result: unknown): unknown[] {
+  if (Array.isArray(result)) return result
+  if (result && typeof result === "object") {
+    const d = (result as { data?: unknown }).data
+    if (Array.isArray(d)) return d
+  }
+  return []
+}

package/src/core/store.ts

@@ -24,8 +24,27 @@ export type Screen =
       completionMessage: string
       hasNextMission: boolean
     }
+  // Server-backed pickers, reachable via the `/model` and `/sessions` slash
+  // commands. They carry their fetched list so the router stays a pure
+  // function of state. `returnTo` is the screen to restore on cancel/select.
+  | { kind: "model_picker"; models: ModelChoice[]; returnTo: Screen }
+  | { kind: "session_list"; sessions: SessionSummary[]; returnTo: Screen }
   | { kind: "error"; variant: ErrorVariant; detail?: string }
 
+/** A selectable AI model, flattened from the server's provider list. */
+export interface ModelChoice {
+  /** Full id passed to session.prompt, e.g. "anthropic/claude-3-5-sonnet". */
+  id: string
+  /** Kid-friendly display label. */
+  label: string
+}
+
+/** A past session, from session.list(). */
+export interface SessionSummary {
+  id: string
+  title: string
+}
+
 export type ErrorVariant =
   | "serve_unreachable"
   | "port_taken"
@@ -86,6 +105,10 @@ export interface KidsClientState {
   toast: ToastState | null
   /** Plugin emitted audit events kept for parent dashboard sync (capped). */
   auditBuffer: unknown[]
+  /** Model id chosen via `/model`; null → server default. Passed to prompt(). */
+  selectedModel: string | null
+  /** Kid-friendly label of selectedModel, for display in the header/toast. */
+  selectedModelLabel: string | null
 }
 
 type Listener = (state: KidsClientState) => void
@@ -107,6 +130,8 @@ const INITIAL: KidsClientState = {
   missionTotal: null,
   toast: null,
   auditBuffer: [],
+  selectedModel: null,
+  selectedModelLabel: null,
 }
 
 const AUDIT_BUFFER_CAP = 500

package/src/index.tsx

@@ -30,6 +30,8 @@ import { Store } from "./core/store.ts"
 import { listInstalledPacks, resolveContext } from "./core/course-pack.ts"
 import { readLastSession, writeLastSession } from "./core/last-session.ts"
 import { isCompletionTrigger, runCheck } from "./core/check-runner.ts"
+import { parseSlash, matchCommand } from "./core/commands.ts"
+import { listModels } from "./core/models.ts"
 import { App } from "./render/ink/App.tsx"
 import { FREE_PLAY_PACK_ID } from "./render/ink/screens/CoursePackPicker.tsx"
 import { detectDangerousTopicEn, detectDangerousTopicZh } from "./dangerous-topic-bridge.ts"
@@ -58,6 +60,7 @@ interface FullHandlers {
   onErrorRetry: () => Promise<void>
   onPickPack: (packId: string) => void
   onMissionNext: () => void
+  onSessionPick: (sessionId: string) => void
 }
 
 interface AppHandlers {
@@ -75,6 +78,9 @@ interface AppHandlers {
   onMissionNext: () => void
   onMissionBack: () => void
   onMissionExit: () => void
+  onModelPick: (modelId: string) => void
+  onSessionPick: (sessionId: string) => void
+  onPickerClose: () => void
   onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
   onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
@@ -230,6 +236,27 @@ function makeHandlers(
     onPickerBack: () => store.update({ screen: { kind: "startup" } }),
     onMissionNext: ifBooted((s) => s.handlers.onMissionNext()),
     onMissionBack: () => store.update({ screen: { kind: "mission" } }),
+    onModelPick: (modelId) => {
+      const sc = store.getSnapshot().screen
+      if (sc.kind !== "model_picker") return
+      const chosen = sc.models.find((m) => m.id === modelId)
+      store.update({
+        selectedModel: modelId,
+        selectedModelLabel: chosen?.label ?? modelId,
+        screen: sc.returnTo,
+      })
+      flashToast(store, {
+        kind: "success",
+        text: (env.locale === "zh-Hans" ? "已切换模型：" : "Model: ") + (chosen?.label ?? modelId),
+      })
+    },
+    onSessionPick: ifBooted((s, id: string) => s.handlers.onSessionPick(id)),
+    onPickerClose: () => {
+      const sc = store.getSnapshot().screen
+      if (sc.kind === "model_picker" || sc.kind === "session_list") {
+        store.update({ screen: sc.returnTo })
+      }
+    },
     // Leave an in-progress mission and return to the startup menu. The serve +
     // session keep running in the background; the kid just re-enters from the
     // picker. Mirrors onHelpBack / onPickerBack.
@@ -431,7 +458,7 @@ async function bootServices(env: KidsClientEnv, store: Store): Promise<ServiceSe
     process.exit(0)
   }
 
-  const handlers = makeFullHandlers(store, env, session, client, serve)
+  const handlers = makeFullHandlers(store, env, session, client, serve, quit)
 
   return { audit, serve, client, session, subscriber, quit, handlers }
 }
@@ -442,6 +469,7 @@ function makeFullHandlers(
   session: SessionManager,
   client: OpencodeClient,
   serve: ServeManager,
+  quit: () => Promise<void>,
 ): FullHandlers {
   const updateLastSession = (): void => {
     writeLastSession(env.configDir, {
@@ -466,6 +494,58 @@ function makeFullHandlers(
     }
   }
 
+  const zh = env.locale === "zh-Hans"
+  const sysMessage = (text: string): void => {
+    store.appendMessage({ id: `sys-${Date.now()}`, actor: "system", text, streaming: false, ts: Date.now() })
+  }
+
+  // Handle a kid-safe `/command`. Returns nothing — it mutates the store /
+  // opens a picker. Unknown commands get a friendly nudge toward /help. Note
+  // `/check` + `/done` are handled earlier in onPrompt (completion triggers)
+  // when inside a mission, so they only reach here outside one.
+  const dispatchSlash = async (text: string): Promise<void> => {
+    const parsed = parseSlash(text)
+    const cmd = parsed ? matchCommand(parsed.name) : null
+    if (!cmd) {
+      sysMessage(zh
+        ? `没有「${parsed?.name ?? text}」这个命令。输入 /help 看看能用哪些。`
+        : `No command "${parsed?.name ?? text}". Type /help to see what's available.`)
+      return
+    }
+    switch (cmd.id) {
+      case "help":
+        store.update({ screen: { kind: "help" } })
+        return
+      case "menu":
+        store.update({ screen: { kind: "startup" } })
+        return
+      case "clear":
+        store.update({ messages: [] })
+        return
+      case "new":
+        session.reset()
+        store.update({ messages: [] })
+        flashToast(store, { kind: "success", text: zh ? "开始一段新对话 ✓" : "New chat ✓" })
+        return
+      case "quit":
+        await quit()
+        return
+      case "check":
+        sysMessage(zh ? "先开始一个项目，再用 /check 验收哦。" : "Start a project first, then use /check.")
+        return
+      case "model": {
+        const models = await listModels(client)
+        store.update({ screen: { kind: "model_picker", models, returnTo: store.getSnapshot().screen } })
+        return
+      }
+      case "sessions": {
+        const sessions = await session.list()
+        store.update({ screen: { kind: "session_list", sessions, returnTo: store.getSnapshot().screen } })
+        return
+      }
+    }
+  }
+
   return {
     onStart: (mode) => {
       if (mode === "help") {
@@ -535,6 +615,11 @@ function makeFullHandlers(
         return
       }
 
+      if (text.trim().startsWith("/")) {
+        await dispatchSlash(text)
+        return
+      }
+
       const hit = env.locale === "zh-Hans" ? detectDangerousTopicZh(text) : detectDangerousTopicEn(text)
       if (hit) {
         store.update({ dangerousTopic: { category: hit, snippet: text } })
@@ -544,7 +629,7 @@ function makeFullHandlers(
       store.update({ thinking: true })
       updateLastSession()
       try {
-        await session.prompt(text)
+        await session.prompt(text, { model: snap.selectedModel ?? undefined })
       } catch (err) {
         store.update({ thinking: false, screen: { kind: "error", variant: "network_down", detail: errMessage(err) } })
       }
@@ -641,6 +726,18 @@ function makeFullHandlers(
         text: env.locale === "zh-Hans" ? `开始：${next.title}` : `Starting: ${next.title}`,
       })
     },
+    onSessionPick: (sessionId) => {
+      session.switchTo(sessionId)
+      const sc = store.getSnapshot().screen
+      const back = sc.kind === "session_list" ? sc.returnTo : { kind: "mission" as const }
+      // We continue the session server-side; the local transcript starts clean
+      // (full rehydration of past messages is a later enhancement).
+      store.update({ messages: [], screen: back })
+      flashToast(store, {
+        kind: "info",
+        text: env.locale === "zh-Hans" ? "已切到这段对话，继续聊吧" : "Switched to that chat — keep going",
+      })
+    },
   }
 }
 

package/src/render/ink/App.tsx

@@ -24,6 +24,7 @@ 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 { PickList } from "./components/PickList.tsx"
 import type { ProviderId } from "../../core/setup.ts"
 
 // Variants where the root cause may be a stale / wrong API key or a missing
@@ -60,6 +61,12 @@ export interface AppDeps {
   onMissionBack: () => void
   /** Leave an in-progress mission and return to the startup menu. */
   onMissionExit: () => void
+  /** Pick an AI model from the `/model` picker (id = "provider/model"). */
+  onModelPick: (modelId: string) => void
+  /** Open a past session from the `/sessions` picker. */
+  onSessionPick: (sessionId: string) => void
+  /** Cancel a model/session picker and go back to where it was opened from. */
+  onPickerClose: () => void
   onSetupSave: (provider: ProviderId, apiKey: string) => Promise<{ ok: true } | { ok: false; reason: string }>
   onSetupContinue: () => Promise<void>
   onSetupSkip: () => void
@@ -156,6 +163,32 @@ function renderScreen(state: ReturnType<Store["getSnapshot"]>, deps: AppDeps): R
           onBack={deps.onMissionBack}
         />
       )
+    case "model_picker": {
+      const zh = deps.locale === "zh-Hans"
+      return (
+        <PickList
+          title={zh ? "选一个 AI 模型" : "Pick an AI model"}
+          items={state.screen.models.map((m) => ({ id: m.id, label: m.label, sublabel: m.id }))}
+          hints={zh ? "[↑↓] 选 · [Enter] 确认 · [Esc] 返回" : "[↑↓] move · [Enter] choose · [Esc] back"}
+          emptyText={zh ? "暂时拿不到模型列表，先用默认的吧。" : "No models available right now — using the default."}
+          onPick={deps.onModelPick}
+          onBack={deps.onPickerClose}
+        />
+      )
+    }
+    case "session_list": {
+      const zh = deps.locale === "zh-Hans"
+      return (
+        <PickList
+          title={zh ? "之前的对话" : "Your past chats"}
+          items={state.screen.sessions.map((s) => ({ id: s.id, label: s.title, sublabel: s.id }))}
+          hints={zh ? "[↑↓] 选 · [Enter] 打开 · [Esc] 返回" : "[↑↓] move · [Enter] open · [Esc] back"}
+          emptyText={zh ? "还没有以前的对话。" : "No earlier chats yet."}
+          onPick={deps.onSessionPick}
+          onBack={deps.onPickerClose}
+        />
+      )
+    }
     case "error":
       return (
         <ErrorScreen

package/src/render/ink/components/CommandSuggestions.tsx

@@ -0,0 +1,47 @@
+/**
+ * Inline slash-command suggestions, shown above the input the moment the kid's
+ * draft starts with "/". Non-interactive on purpose: the kid keeps typing and
+ * presses Enter, which submits the draft to onPrompt where it's dispatched.
+ * This gives opencode's "type / → see commands" feel without intercepting
+ * keystrokes out of the text input. The closest match is highlighted.
+ */
+
+import React from "react"
+import { Box, Text } from "ink"
+import { getTheme } from "../theme.ts"
+import { filterCommands, commandLabel, commandHint, type Locale } from "../../../core/commands.ts"
+
+const MAX_SHOWN = 6
+
+export function CommandSuggestions({ query, locale }: { query: string; locale: Locale }): React.ReactElement | null {
+  const theme = getTheme()
+  const matches = filterCommands(query).slice(0, MAX_SHOWN)
+  if (matches.length === 0) {
+    return (
+      <Box marginBottom={1} flexDirection="column">
+        <Text color={theme.fgDim}>
+          {locale === "zh-Hans" ? "没有这个命令 — 试试 /help" : "No such command — try /help"}
+        </Text>
+      </Box>
+    )
+  }
+  // Highlight an exact-ish lead match (full slash typed) so Enter feels obvious.
+  const q = query.trim().toLowerCase()
+  return (
+    <Box marginBottom={1} flexDirection="column">
+      {matches.map((c) => {
+        const lead = c.slash === q || c.aliases?.includes(q)
+        return (
+          <Box key={c.id}>
+            <Text color={lead ? theme.kid : theme.accent} bold={lead}>{c.slash}</Text>
+            <Text color={theme.fg}>{"  "}{commandLabel(c, locale)}</Text>
+            <Text color={theme.fgDim} dimColor>{"  — "}{commandHint(c, locale)}</Text>
+          </Box>
+        )
+      })}
+      <Text color={theme.fgDim}>
+        {locale === "zh-Hans" ? "输入命令后按 Enter 执行" : "Finish the command and press Enter"}
+      </Text>
+    </Box>
+  )
+}

package/src/render/ink/components/Input.tsx

@@ -14,7 +14,7 @@ interface InputProps {
 export function Input({ value, onChange, onSubmit, placeholder, disabled }: InputProps): React.ReactElement {
   const theme = getTheme()
   return (
-    <Box borderStyle="single" borderColor={theme.fgDim} paddingX={1}>
+    <Box borderStyle="single" borderColor={theme.fgDim} paddingX={1} width="100%">
       <Text color={theme.kid}>💬 </Text>
       {disabled ? (
         <Text color={theme.fgDim} dimColor>

package/src/render/ink/components/PickList.tsx

@@ -0,0 +1,62 @@
+/**
+ * Generic full-width selectable list — ↑/↓ to move, Enter to pick, Esc to go
+ * back. Reused by the `/model` and `/sessions` pickers so they share the
+ * kid-friendly look of CoursePackPicker without duplicating the keyboard idiom.
+ */
+
+import React, { useState } from "react"
+import { Box, Text, useInput } from "ink"
+import { getTheme } from "../theme.ts"
+
+export interface PickItem {
+  id: string
+  label: string
+  /** Optional secondary line (e.g. provider, or session id). */
+  sublabel?: string
+}
+
+interface PickListProps {
+  title: string
+  items: PickItem[]
+  hints: string
+  emptyText: string
+  onPick: (id: string) => void
+  onBack: () => void
+}
+
+export function PickList({ title, items, hints, emptyText, onPick, onBack }: PickListProps): React.ReactElement {
+  const theme = getTheme()
+  const [idx, setIdx] = useState(0)
+  useInput((_, key) => {
+    if (key.escape || key.leftArrow) onBack()
+    else if (key.upArrow) setIdx((i) => Math.max(0, i - 1))
+    else if (key.downArrow) setIdx((i) => Math.min(items.length - 1, i + 1))
+    else if (key.return && items[idx]) onPick(items[idx]!.id)
+  })
+  return (
+    <Box flexDirection="column" borderStyle="single" borderColor={theme.accent} paddingX={2} paddingY={1} width="100%">
+      <Text color={theme.accent} bold>{title}</Text>
+      <Box marginTop={1} flexDirection="column">
+        {items.length === 0 ? (
+          <Text color={theme.fgDim}>{emptyText}</Text>
+        ) : (
+          items.map((item, i) => {
+            const active = i === idx
+            return (
+              <Box key={item.id}>
+                <Text color={active ? theme.kid : theme.fg}>{active ? "▶ " : "  "}</Text>
+                <Box flexDirection="column" flexGrow={1}>
+                  <Text color={active ? theme.accent : theme.fg} bold={active}>{item.label}</Text>
+                  {item.sublabel && <Text color={theme.fgDim} dimColor={!active}>  {item.sublabel}</Text>}
+                </Box>
+              </Box>
+            )
+          })
+        )}
+      </Box>
+      <Box marginTop={1}>
+        <Text color={theme.accent}>{hints}</Text>
+      </Box>
+    </Box>
+  )
+}

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

@@ -16,6 +16,7 @@ import { ChatStream } from "../components/ChatStream.tsx"
 import { Input } from "../components/Input.tsx"
 import { Thinking } from "../components/Thinking.tsx"
 import { Toast } from "../components/Toast.tsx"
+import { CommandSuggestions } from "../components/CommandSuggestions.tsx"
 import { getTheme } from "../theme.ts"
 import { useVoiceInput } from "../useVoiceInput.ts"
 import type { KidsClientState } from "../../../core/store.ts"
@@ -40,17 +41,24 @@ export function MissionScreen({ state, locale, onPrompt, onAbort, onExit }: Miss
   // they're writing, so spacebar must stay a literal space there.
   const canTalk = !state.thinking && state.pendingPermission === null && draft.trim() === "" && voice.ready
 
+  // ← (left arrow) is the kid-facing "go back" key, matching TourScreen's ←.
+  // It only leaves the mission when the input box is empty so it never fights
+  // TextInput's cursor movement mid-typing (same empty-draft gate as talk).
+  //
   // Esc is overloaded so it never eats the kid's typing: while recording it
   // cancels voice; while the AI is thinking it interrupts; with text typed it
-  // clears the draft; when idle + empty it leaves back to the startup menu (so
-  // the kid isn't trapped here — dogfood feedback).
+  // clears the draft; when idle + empty it also leaves back to the startup menu
+  // (so the kid isn't trapped here — dogfood feedback).
+  const canGoBack = !state.thinking && draft.length === 0
   useInput((input, key) => {
     if (voiceBusy) {
       if (key.escape) voice.cancel()
       else if (key.return || input === " ") voice.stopListening()
       return
     }
-    if (key.escape) {
+    if (key.leftArrow && canGoBack) {
+      onExit()
+    } else if (key.escape) {
       if (state.thinking) onAbort()
       else if (draft.length > 0) setDraft("")
       else onExit()
@@ -61,11 +69,11 @@ export function MissionScreen({ state, locale, onPrompt, onAbort, onExit }: Miss
   })
 
   const hint = locale === "zh-Hans"
-    ? "提示：按「空格」对小助手说话 · 打 /check 或「我做完了」验收 · Esc 打断 AI / 返回菜单"
-    : "Tip: press Space to talk · type /check or 'I'm done' to validate · Esc interrupts AI / returns to menu"
+    ? "提示：打 / 看命令 · 按「空格」说话 · 「我做完了」验收 · 按 ← 返回菜单 · AI 说话时 Esc 打断"
+    : "Tip: type / for commands · Space to talk · 'I'm done' to validate · ← to go back · Esc interrupts the AI"
 
   return (
-    <Box flexDirection="column">
+    <Box flexDirection="column" flexGrow={1}>
       <Header
         packTitle={state.packTitle}
         missionTitle={state.missionTitle}
@@ -82,6 +90,11 @@ export function MissionScreen({ state, locale, onPrompt, onAbort, onExit }: Miss
           </Box>
         )}
       </Box>
+      {!voiceBusy && draft.trim().startsWith("/") && (
+        <Box marginTop={1}>
+          <CommandSuggestions query={draft} locale={locale} />
+        </Box>
+      )}
       <Box marginTop={1}>
         {voiceBusy ? (
           <VoiceBar voiceState={voice.voiceState} meter={voice.meter} mode={voice.mode} locale={locale} theme={theme} />

package/src/voice-demo.tsx

@@ -37,6 +37,8 @@ function baseState(messages: ChatMessage[]): KidsClientState {
     missionTotal: 1,
     toast: null,
     auditBuffer: [],
+    selectedModel: null,
+    selectedModelLabel: null,
   }
 }