@kidsinai/kids-client 0.0.1

package/src/core/last-session.ts

@@ -0,0 +1,48 @@
+/**
+ * Persists "last session" metadata so the [r] Resume option on the
+ * Startup screen has something to offer.
+ *
+ * Note: this is NOT LLM-session resumption (PRD §5.3, deferred to V1
+ * because client owns serve subprocess). It only remembers which
+ * course/mission the kid was working on so they jump back into the
+ * MissionScreen without re-entering flags.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+export interface LastSession {
+  coursePack: string | null
+  mission: string | null
+  /** ISO timestamp of the last user action. */
+  lastActiveAt: string
+  /** Working directory at the time, so resume picks the right project. */
+  projectDir: string
+}
+
+export function lastSessionPath(configDir: string): string {
+  return join(configDir, "last-session.json")
+}
+
+export function readLastSession(configDir: string): LastSession | null {
+  const path = lastSessionPath(configDir)
+  if (!existsSync(path)) return null
+  try {
+    const raw = readFileSync(path, "utf8")
+    const parsed = JSON.parse(raw) as LastSession
+    if (typeof parsed.lastActiveAt !== "string") return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+export function writeLastSession(configDir: string, session: LastSession): void {
+  const path = lastSessionPath(configDir)
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, JSON.stringify(session, null, 2), "utf8")
+  } catch {
+    // Resume is a nice-to-have; silently skip if we can't persist.
+  }
+}

package/src/core/serve-manager.ts

@@ -0,0 +1,132 @@
+/**
+ * Owns the local `opencode serve` subprocess for the lifetime of this client.
+ *
+ * Per docs/v2-api-verification.md Q3 (resolved 2026-05-16): plugin cannot
+ * publish custom events through SDK public API, so the audit pipeline
+ * tails serve stderr and parses `[kids-audit] {...}` lines.
+ *
+ * V0 scope cut: client crash kills serve. Session-resume (PRD §5.3) is
+ * deferred to V1. See Q3 spike notes.
+ */
+
+import { spawn, type Subprocess } from "bun"
+
+export type ServeReadiness =
+  | { kind: "already_running" }
+  | { kind: "spawned"; pid: number }
+  | { kind: "timeout"; lastError: string }
+
+export interface ServeManagerOptions {
+  baseUrl: string
+  serverPassword: string
+  opencodeBin: string
+  /** Max wait for readiness probe in ms. Default 10s. */
+  readyTimeoutMs?: number
+  /** Called for every parsed `[kids-audit]` JSON line on stderr. */
+  onAuditLine?: (event: unknown) => void
+  /** Called for every other (non-audit) stderr line. Useful for debug log. */
+  onDebugLine?: (line: string) => void
+}
+
+export class ServeManager {
+  private child: Subprocess | null = null
+  private opts: ServeManagerOptions
+
+  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.
+   */
+  async ensureReady(): Promise<ServeReadiness> {
+    if (await this.probe()) return { kind: "already_running" }
+
+    const url = new URL(this.opts.baseUrl)
+    const proc = spawn({
+      cmd: [this.opts.opencodeBin, "serve", "--hostname", url.hostname, "--port", url.port || "4096"],
+      env: {
+        ...process.env,
+        OPENCODE_SERVER_PASSWORD: this.opts.serverPassword,
+      },
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+    this.child = proc
+
+    if (proc.stderr) void this.pipeStderr(proc.stderr)
+
+    const timeout = this.opts.readyTimeoutMs ?? 10_000
+    const start = Date.now()
+    let lastError = "no response"
+    while (Date.now() - start < timeout) {
+      if (await this.probe()) return { kind: "spawned", pid: proc.pid ?? -1 }
+      await new Promise((r) => setTimeout(r, 200))
+      lastError = "still booting"
+    }
+    return { kind: "timeout", lastError }
+  }
+
+  /** Kill the serve child (V0 MVP: on client exit). */
+  async shutdown(): Promise<void> {
+    if (this.child && !this.child.killed) {
+      this.child.kill()
+      await this.child.exited
+    }
+    this.child = null
+  }
+
+  /** GET /app with Basic Auth. Returns true on 200. */
+  private async probe(): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.opts.baseUrl}/app`, {
+        headers: {
+          authorization: "Basic " + btoa(`:${this.opts.serverPassword}`),
+        },
+      })
+      return res.ok
+    } catch {
+      return false
+    }
+  }
+
+  private async pipeStderr(stream: ReadableStream<Uint8Array>): Promise<void> {
+    const decoder = new TextDecoder()
+    let buf = ""
+    const reader = stream.getReader()
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+      buf += decoder.decode(value, { stream: true })
+      let nl: number
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl)
+        buf = buf.slice(nl + 1)
+        this.handleLine(line)
+      }
+    }
+    if (buf.length > 0) this.handleLine(buf)
+  }
+
+  private handleLine(line: string): void {
+    if (!line) return
+    const audit = parseAuditLine(line)
+    if (audit) this.opts.onAuditLine?.(audit)
+    else this.opts.onDebugLine?.(line)
+  }
+}
+
+export function parseAuditLine(line: string): unknown | null {
+  const prefixes = ["[kids-audit] ", "[kids-tui-audit] "]
+  for (const prefix of prefixes) {
+    if (line.startsWith(prefix)) {
+      try {
+        return JSON.parse(line.slice(prefix.length))
+      } catch {
+        return null
+      }
+    }
+  }
+  return null
+}

package/src/core/session.ts

@@ -0,0 +1,63 @@
+/**
+ * Session lifecycle wrapper. Thin shim around SDK v2 session resource.
+ *
+ * Public API:
+ * - createSession(): create a new session, return its ID
+ * - prompt(text): send a kid message; returns immediately (SSE delivers stream)
+ * - abort(): stop the in-flight prompt; session stays live
+ *
+ * Errors propagate to caller; UI maps to ErrorScreen variants.
+ */
+
+import type { OpencodeClient } from "./connection.ts"
+
+export class SessionManager {
+  private client: OpencodeClient
+  private currentSessionId: string | null = null
+
+  constructor(client: OpencodeClient) {
+    this.client = client
+  }
+
+  getId(): string | null {
+    return this.currentSessionId
+  }
+
+  async create(): Promise<string> {
+    const api = (this.client as unknown as { session?: { create: (input?: 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({})
+    const id = extractId(result)
+    if (!id) throw new Error("SDK v2 session.create returned no id")
+    this.currentSessionId = 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
+    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,
+    })
+  }
+
+  async abort(): Promise<void> {
+    if (!this.currentSessionId) return
+    const api = (this.client as unknown as { session?: { abort: (sessionID: string) => Promise<unknown> } }).session
+    if (!api?.abort) return
+    await api.abort(this.currentSessionId)
+  }
+}
+
+function extractId(result: unknown): string | null {
+  if (typeof result === "string") return result
+  if (result && typeof result === "object") {
+    const r = result as { id?: string; data?: { id?: string } }
+    return r.id ?? r.data?.id ?? null
+  }
+  return null
+}

package/src/core/store.ts

@@ -0,0 +1,165 @@
+/**
+ * In-process state store. Pure TS, no Ink imports — V1 Tauri (WebView)
+ * reuses this verbatim.
+ *
+ * Subscription pattern: dumb pub/sub. Renderers (Ink today, WebView later)
+ * subscribe to changes via getSnapshot + subscribe pair, suitable for
+ * React 18 useSyncExternalStore.
+ */
+
+export type Screen =
+  | { kind: "loading"; message?: string }
+  | { kind: "startup" }
+  | { kind: "mission" }
+  | { kind: "help" }
+  | { kind: "course_picker" }
+  | {
+      kind: "mission_complete"
+      missionId: string
+      missionTitle: string | null
+      passed: number
+      total: number
+      completionMessage: string
+      hasNextMission: boolean
+    }
+  | { kind: "error"; variant: ErrorVariant; detail?: string }
+
+export type ErrorVariant =
+  | "serve_unreachable"
+  | "network_down"
+  | "stars_exhausted"
+  | "auth_failed"
+  | "config_missing"
+  | "ai_hung"
+
+export interface ChatMessage {
+  id: string
+  actor: "kid" | "agent" | "system"
+  text: string
+  /** Stream still flowing for this message. */
+  streaming: boolean
+  ts: number
+}
+
+export interface PendingPermission {
+  requestID: string
+  tool?: string
+  /** Free-form text the kid sees ("AI 想要读取 index.html") */
+  summary: string
+  metadata: Record<string, unknown>
+  /** Plugin-reported predicted Stars cost for this tool call. */
+  starsEstimated?: number
+}
+
+export interface DangerousTopic {
+  category: "self_harm" | "violence" | "adult" | "other"
+  snippet: string
+}
+
+export interface ToastState {
+  kind: "info" | "warn" | "success"
+  text: string
+}
+
+export interface KidsClientState {
+  screen: Screen
+  sessionId: string | null
+  messages: ChatMessage[]
+  starsBalance: number
+  starsBudget: number
+  pendingPermission: PendingPermission | null
+  dangerousTopic: DangerousTopic | null
+  thinking: boolean
+  /** Set when wrapper passed --course or KIDS_COURSE_PACK. */
+  coursePack: string | null
+  mission: string | null
+  /** Resolved from CoursePack metadata. null in free-play. */
+  packTitle: string | null
+  missionTitle: string | null
+  /** 1-based current mission index within pack.missions; null in free-play. */
+  missionIndex: number | null
+  missionTotal: number | null
+  /** Transient toast (auto-dismisses after a few seconds in the orchestrator). */
+  toast: ToastState | null
+  /** Plugin emitted audit events kept for parent dashboard sync (capped). */
+  auditBuffer: unknown[]
+}
+
+type Listener = (state: KidsClientState) => void
+
+const INITIAL: KidsClientState = {
+  screen: { kind: "loading" },
+  sessionId: null,
+  messages: [],
+  starsBalance: 0,
+  starsBudget: 0,
+  pendingPermission: null,
+  dangerousTopic: null,
+  thinking: false,
+  coursePack: null,
+  mission: null,
+  packTitle: null,
+  missionTitle: null,
+  missionIndex: null,
+  missionTotal: null,
+  toast: null,
+  auditBuffer: [],
+}
+
+const AUDIT_BUFFER_CAP = 500
+
+export class Store {
+  private state: KidsClientState = INITIAL
+  private listeners = new Set<Listener>()
+
+  getSnapshot(): KidsClientState {
+    return this.state
+  }
+
+  subscribe(fn: Listener): () => void {
+    this.listeners.add(fn)
+    return () => this.listeners.delete(fn)
+  }
+
+  update(patch: Partial<KidsClientState>): void {
+    this.state = { ...this.state, ...patch }
+    this.notify()
+  }
+
+  appendMessage(msg: ChatMessage): void {
+    this.state = { ...this.state, messages: [...this.state.messages, msg] }
+    this.notify()
+  }
+
+  appendDelta(messageId: string, delta: string): void {
+    const messages = this.state.messages.map((m) =>
+      m.id === messageId ? { ...m, text: m.text + delta } : m,
+    )
+    this.state = { ...this.state, messages }
+    this.notify()
+  }
+
+  endStream(messageId: string): void {
+    const messages = this.state.messages.map((m) =>
+      m.id === messageId ? { ...m, streaming: false } : m,
+    )
+    this.state = { ...this.state, messages, thinking: false }
+    this.notify()
+  }
+
+  pushAudit(event: unknown): void {
+    const next = [...this.state.auditBuffer, event]
+    if (next.length > AUDIT_BUFFER_CAP) next.shift()
+    this.state = { ...this.state, auditBuffer: next }
+    this.notify()
+  }
+
+  reset(): void {
+    this.state = INITIAL
+    this.notify()
+  }
+
+  private notify(): void {
+    for (const fn of this.listeners) fn(this.state)
+  }
+}

package/src/dangerous-topic-bridge.ts

@@ -0,0 +1,50 @@
+/**
+ * Thin re-export so the client can reuse kids-tui-plugin's pattern list
+ * without duplicating it. If the pattern set evolves there, we pick up
+ * the change for free via the workspace dep.
+ *
+ * The kids-tui-plugin export is the source of truth.
+ */
+
+export type DangerousCategory = "self_harm" | "violence" | "adult" | "other"
+
+interface DangerousMatcher {
+  category: DangerousCategory
+  patterns: RegExp[]
+}
+
+// Curated mirror of the patterns we know live in kids-tui-plugin/src/dangerous-topic.ts.
+// Keeping these here as a redundancy in case the upstream module isn't
+// loaded yet (the workspace dep should resolve, but at the time of this
+// commit kids-tui-plugin hasn't been imported into kids-client tests).
+//
+// When the actual file becomes available via the workspace, replace
+// these arrays with `import { detect } from "@kidsinai/kids-opencode-tui-plugin"`.
+const ZH: DangerousMatcher[] = [
+  { category: "self_harm", patterns: [/想.{0,3}(自杀|死|结束.{0,2}生命)/, /(伤害自己|自残)/] },
+  { category: "violence", patterns: [/(怎么.{0,3}杀|做.{0,2}炸弹|做.{0,2}武器)/] },
+  { category: "adult", patterns: [/(色情|裸照|性.{0,2}行为)/] },
+]
+const EN: DangerousMatcher[] = [
+  { category: "self_harm", patterns: [/\b(kill\s+myself|end\s+my\s+life|suicide|self[-\s]?harm)\b/i] },
+  { category: "violence", patterns: [/\b(make\s+a\s+bomb|how\s+to\s+kill|weapon)\b/i] },
+  { category: "adult", patterns: [/\b(nude|porn|sexual\s+act)\b/i] },
+]
+
+function detect(text: string, matchers: DangerousMatcher[]): DangerousCategory | null {
+  if (!text) return null
+  for (const m of matchers) {
+    for (const p of m.patterns) {
+      if (p.test(text)) return m.category
+    }
+  }
+  return null
+}
+
+export function detectDangerousTopicZh(text: string): DangerousCategory | null {
+  return detect(text, ZH)
+}
+
+export function detectDangerousTopicEn(text: string): DangerousCategory | null {
+  return detect(text, EN)
+}