@linxin666/dsh-client-ui-task-board 0.1.1

package/src/core/controller.ts

@@ -0,0 +1,379 @@
+/**
+ * Board controller: the single owner of task-ledger state and view state.
+ *
+ * It keeps the ledger in memory, persists every mutation through the
+ * {@link TaskStore}, drives real executions through the
+ * {@link ExecutionService}, and closes the board view whenever the user
+ * navigates to a session (the sessions-list `current` selection changes).
+ * Framework-free (structural runtime faces) so the whole orchestration is
+ * unit-testable with fakes.
+ */
+import { ExecutionService, type ExecutionEvent } from './execution.ts'
+import { isValidCron, nextRunAtMs } from './schedule.ts'
+import type { TaskStore } from './store.ts'
+import {
+  createTask, settleExecution, startExecution, withSchedule, withStatus,
+  type NewTaskInput, type TaskRecord, type TaskStatus,
+} from './tasks.ts'
+
+/** The sessions face the controller needs for navigation awareness. */
+export interface SessionsControllerFace {
+  list: {
+    getSnapshot(): { current: string | undefined }
+    subscribe(fn: () => void): () => void
+  }
+  /** Select a session as current (navigates the conversation view). */
+  open(id: string): void
+}
+
+/** Controller dependencies (all swappable in tests). */
+export interface ControllerDeps {
+  store: TaskStore
+  exec: ExecutionService
+  sessions: SessionsControllerFace
+  /** Clock; defaults to Date.now. */
+  now?: () => number
+  /** Id minting; defaults to a random-uuid. */
+  uuid?: () => string
+  /** Debounce (ms) for session-list-changed reconciles; defaults to 350. */
+  reconcileDebounceMs?: number
+}
+
+/** Immutable controller snapshot for UI subscriptions. */
+export interface ControllerSnapshot {
+  tasks: readonly TaskRecord[]
+  boardOpen: boolean
+  selectedTaskId: string | undefined
+}
+
+/** The selected task (resolved from the ledger), or undefined. */
+export function selectedTaskOf(snapshot: ControllerSnapshot): TaskRecord | undefined {
+  if (snapshot.selectedTaskId === undefined) return undefined
+  return snapshot.tasks.find(task => task.id === snapshot.selectedTaskId)
+}
+
+function randomUuid(): string {
+  const bytes = globalThis.crypto?.getRandomValues(new Uint8Array(16))
+  if (bytes === undefined) {
+    // Non-secure fallback (tests, odd environments).
+    return `t-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+  }
+  bytes[6] = (bytes[6] & 0x0f) | 0x40
+  bytes[8] = (bytes[8] & 0x3f) | 0x80
+  const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+/** Read the current selection off a session-list snapshot (structural). */
+function currentOf(sessions: SessionsControllerFace): string | undefined {
+  return sessions.list.getSnapshot().current
+}
+
+/**
+ * Board controller (see module doc). All mutations bump the snapshot and
+ * persist through the store; UI and DOM mounts subscribe and re-render.
+ */
+export class BoardController {
+  private tasks: TaskRecord[] = []
+  private boardOpen = false
+  private selectedTaskId: string | undefined
+  private listeners = new Set<() => void>()
+  private disposers: Array<() => void> = []
+  private readonly now: () => number
+  private readonly uuid: () => string
+
+  /** @param deps - store, execution service, and the sessions navigation face. */
+  constructor(private readonly deps: ControllerDeps) {
+    this.now = deps.now ?? (() => Date.now())
+    this.uuid = deps.uuid ?? randomUuid
+  }
+
+  // --- lifecycle -------------------------------------------------------------
+
+  /** Load the persisted ledger and start the navigation/status subscriptions. */
+  start(): void {
+    this.tasks = this.deps.store.load()
+    void this.reconcileRunningTasks()
+    this.disposers.push(this.deps.sessions.list.subscribe(() => {
+      this.onSessionsChanged()
+    }))
+    this.notify()
+  }
+
+  /** Stop all subscriptions and drop retained state (idempotent). */
+  dispose(): void {
+    for (const dispose of this.disposers.splice(0)) dispose()
+    this.listeners.clear()
+    if (this.reconcileTimer !== undefined) clearTimeout(this.reconcileTimer)
+    this.reconcileTimer = undefined
+  }
+
+  // --- snapshot / subscription ------------------------------------------------
+
+  getSnapshot(): ControllerSnapshot {
+    return {
+      tasks: this.tasks,
+      boardOpen: this.boardOpen,
+      selectedTaskId: this.selectedTaskId,
+    }
+  }
+
+  subscribe(fn: () => void): () => void {
+    this.listeners.add(fn)
+    return () => { this.listeners.delete(fn) }
+  }
+
+  // --- view state -------------------------------------------------------------
+
+  openBoard(): void {
+    if (this.boardOpen) return
+    // Baseline the selection the board opened against: the board stays open
+    // until the user navigates (selection changes), never on mere status
+    // updates of the already-selected session.
+    this.lastCurrent = currentOf(this.deps.sessions)
+    this.boardOpen = true
+    this.notify()
+  }
+
+  closeBoard(): void {
+    if (!this.boardOpen) return
+    this.boardOpen = false
+    this.notify()
+  }
+
+  toggleBoard(): void {
+    if (this.boardOpen) this.closeBoard()
+    else this.openBoard()
+  }
+
+  openTask(id: string): void {
+    if (this.tasks.some(task => task.id === id)) {
+      this.selectedTaskId = id
+      this.notify()
+    }
+  }
+
+  closeTask(): void {
+    if (this.selectedTaskId === undefined) return
+    this.selectedTaskId = undefined
+    this.notify()
+  }
+
+  // --- task mutations ---------------------------------------------------------
+
+  createTask(input: NewTaskInput): TaskRecord | undefined {
+    const title = input.title.trim()
+    if (title === '') return undefined
+    const task = createTask(input, this.now(), this.uuid())
+    this.tasks = [...this.tasks, task]
+    this.persistAndNotify()
+    return task
+  }
+
+  updateTask(id: string, patch: Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt'>>): void {
+    this.tasks = this.tasks.map(task => task.id === id
+      ? { ...task, ...patch, updatedAt: this.now() }
+      : task)
+    this.persistAndNotify()
+  }
+
+  moveTask(id: string, status: TaskStatus): void {
+    this.tasks = this.tasks.map(task => task.id === id ? withStatus(task, status, this.now()) : task)
+    this.persistAndNotify()
+  }
+
+  deleteTask(id: string): void {
+    this.tasks = this.tasks.filter(task => task.id !== id)
+    if (this.selectedTaskId === id) this.selectedTaskId = undefined
+    this.persistAndNotify()
+  }
+
+  // --- scheduling ---------------------------------------------------------------
+
+  /**
+   * Update a task's schedule rule. A blank or invalid cron expression is
+   * rejected (returns false, state untouched). When the rule ends up enabled
+   * the next run instant is computed immediately; a disabled rule carries no
+   * next-run instant.
+   * @param id - the task to schedule.
+   * @param patch - fields to change (absent fields keep their current value).
+   * @returns true when applied, false when rejected (invalid cron / unknown task).
+   */
+  setSchedule(id: string, patch: { enabled?: boolean; cron?: string }): boolean {
+    const task = this.tasks.find(candidate => candidate.id === id)
+    if (task === undefined) return false
+    const current = task.schedule
+    const cron = (patch.cron ?? current?.cron ?? '').trim()
+    if (cron === '' || !isValidCron(cron)) return false
+    const enabled = patch.enabled ?? current?.enabled ?? false
+    const nextRunAt = enabled ? nextRunAtMs(cron, this.now()) : undefined
+    this.tasks = this.tasks.map(candidate =>
+      candidate.id === id ? withSchedule(candidate, { enabled, cron, nextRunAt }, this.now()) : candidate)
+    this.persistAndNotify()
+    return true
+  }
+
+  /**
+   * Roll a task's schedule forward (scheduler callback): persist the next due
+   * instant and the trigger instant of this run. No-op when the task has no
+   * schedule rule (it was deleted mid-tick, for example).
+   */
+  applyScheduleNextRun(id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined): void {
+    this.tasks = this.tasks.map(task =>
+      task.id === id && task.schedule !== undefined
+        ? withSchedule(task, { nextRunAt, lastTriggeredAt }, this.now())
+        : task)
+    this.persistAndNotify()
+  }
+
+  /**
+   * Jump to an execution's session transcript. Selecting the session changes
+   * `current`, which closes the board (the conversation view takes over).
+   * @param sessionId - the execution session to open.
+   */
+  openSession(sessionId: string): void {
+    this.deps.sessions.open(sessionId)
+  }
+
+  // --- execution ---------------------------------------------------------------
+
+  /**
+   * Execute a task for real: move it to 'running', open an execution record,
+   * and hand off to the ExecutionService. A second call while the task is
+   * already running is ignored.
+   */
+  async runTask(id: string): Promise<boolean> {
+    const task = this.tasks.find(candidate => candidate.id === id)
+    if (task === undefined || task.status === 'running') return false
+    const { task: next, execution } = startExecution(task, this.now(), this.uuid())
+    this.tasks = this.tasks.map(candidate => candidate.id === id ? next : candidate)
+    this.persistAndNotify()
+    // This page owns the settlement of its own launches: the live watch
+    // (ExecutionService.run) settles on the turn boundary, and list
+    // reconciliation must not pre-empt it with a session that has not
+    // started a turn yet (its list row is idle, not completed).
+    this.activeExecutionIds.add(execution.id)
+    await this.deps.exec.run(next, execution, (event) => { this.handleExecutionEvent(event) })
+    return true
+  }
+
+  /** Re-run a settled task: move it back to 'todo' first, then execute. */
+  async rerunTask(id: string): Promise<void> {
+    const task = this.tasks.find(candidate => candidate.id === id)
+    if (task === undefined) return
+    if (task.status !== 'running') {
+      this.tasks = this.tasks.map(candidate => candidate.id === id ? withStatus(candidate, 'todo', this.now()) : candidate)
+      this.persistAndNotify()
+    }
+    await this.runTask(id)
+  }
+
+  private handleExecutionEvent(event: ExecutionEvent): void {
+    if (event.kind === 'started') {
+      this.tasks = this.tasks.map(task => task.id === event.taskId
+        ? attachSessionId(task, event.executionId, event.sessionId, this.now())
+        : task)
+      this.persistAndNotify()
+      return
+    }
+    this.activeExecutionIds.delete(event.executionId)
+    this.tasks = this.tasks.map(task => task.id === event.taskId
+      ? settleExecution(task, event.executionId, event.outcome, this.now(), event.error)
+      : task)
+    this.persistAndNotify()
+  }
+
+  // --- internals ---------------------------------------------------------------
+
+  /** Reconcile running tasks and close the board when the user navigates. */
+  private onSessionsChanged(): void {
+    // Background/leftover executions settle through the session list (their
+    // conversation snapshots stay cold until opened). Coalesce the burst of
+    // list notifications into one reconcile pass instead of fanning out a
+    // history read per notification; see scheduleReconcile.
+    this.scheduleReconcile()
+    if (!this.boardOpen) return
+    const current = currentOf(this.deps.sessions)
+    if (current !== this.lastCurrent) this.closeBoard()
+    this.lastCurrent = current
+  }
+
+  private lastCurrent: string | undefined = undefined
+
+  /** Execution ids launched on this page; they settle via their live watch, never list reconciliation. */
+  private readonly activeExecutionIds = new Set<string>()
+
+  /** Debounce timer for {@link reconcileRunningTasks}. */
+  private reconcileTimer: ReturnType<typeof setTimeout> | undefined = undefined
+
+  /** Whether a reconcile pass is underway (single-flight guard). */
+  private reconcileInFlight = false
+
+  /**
+   * Debounce + single-flight trigger for the running-task reconciliation.
+   * Session-list notifications arrive in bursts (one per session status
+   * change); both guards together keep a burst from reading the history API
+   * once per running task.
+   */
+  private scheduleReconcile(): void {
+    if (this.reconcileTimer !== undefined) return
+    this.reconcileTimer = setTimeout(() => {
+      this.reconcileTimer = undefined
+      void this.reconcileRunningTasks()
+    }, this.deps.reconcileDebounceMs ?? 350)
+  }
+
+  /** Settle tasks left 'running' whose sessions already finished. */
+  private async reconcileRunningTasks(): Promise<void> {
+    if (this.reconcileInFlight) return
+    this.reconcileInFlight = true
+    try {
+      type Settled = Extract<ExecutionEvent, { kind: 'settled' }>
+      const events: Array<{ task: TaskRecord; event: Settled }> = []
+      for (const task of this.tasks) {
+        if (task.status !== 'running') continue
+        const execution = task.executions[task.executions.length - 1]
+        // Runs launched on this page settle through their live watch (turn
+        // boundary); reconciliation exists for background/leftover runs.
+        if (execution !== undefined && this.activeExecutionIds.has(execution.id)) continue
+        const event = await this.deps.exec.reconcile(task)
+        if (event !== undefined && event.kind === 'settled') events.push({ task, event })
+      }
+      if (events.length === 0) return
+      let changed = false
+      for (const { task, event } of events) {
+        const next = settleExecution(task, event.executionId, event.outcome, this.now(), event.error)
+        if (next === task) continue
+        this.tasks = this.tasks.map(candidate => candidate.id === task.id ? next : candidate)
+        changed = true
+      }
+      if (changed) this.persistAndNotify()
+    } finally {
+      this.reconcileInFlight = false
+    }
+  }
+
+  private persistAndNotify(): void {
+    this.deps.store.save(this.tasks)
+    this.notify()
+  }
+
+  private notify(): void {
+    for (const fn of [...this.listeners]) fn()
+  }
+}
+
+/** Record which session ran an execution (once the execution service reports it). */
+function attachSessionId(
+  task: TaskRecord,
+  executionId: string,
+  sessionId: string,
+  now: number,
+): TaskRecord {
+  return {
+    ...task,
+    updatedAt: now,
+    executions: task.executions.map(execution =>
+      execution.id === executionId ? { ...execution, sessionId } : execution),
+  }
+}

package/src/core/execution.ts

@@ -0,0 +1,259 @@
+/**
+ * Execution service: runs a task through dsh's real session machinery.
+ *
+ * The board's "run" button must make dsh actually work, not fake a status:
+ * the service connects a real session (workspace blank-session reuse or
+ * `session.create` on the host via the workspaces service), renames it to
+ * the task title, sends the task prompt with `session.prompt`, and then
+ * watches the session's conversation snapshot until its turn settles. The
+ * task board controller consumes {@link ExecutionEvent}s to move the card
+ * running → done/failed and to keep the execution record.
+ *
+ * Deliberately framework-free: the runtime faces are declared structurally
+ * (a narrow slice of the real `ctx.sessions` / `ctx.workspaces` contracts)
+ * so tests drive it with plain fakes.
+ */
+import type { ExecutionRecord, TaskRecord } from './tasks.ts'
+
+/** The narrow sessions face the service needs. */
+export interface SessionsExecutionFace {
+  list: {
+    getSnapshot(): {
+      /** Baseline arrival lifecycle — 'pending' until the host list has loaded. */
+      phase: 'pending' | 'ready'
+      byId: Record<string, { running: boolean; completed?: boolean }>
+    }
+    subscribe(fn: () => void): () => void
+  }
+  binding(id: string): { session: SessionDriver } | undefined
+}
+
+/** The narrow workspaces face the service needs. */
+export interface WorkspacesExecutionFace {
+  list: {
+    getSnapshot(): {
+      items: readonly { workspaceId: string }[]
+      recentWorkspaceId: string | undefined
+    }
+  }
+  connectWorkspace(workspaceId: string): Promise<string>
+}
+
+/** One raw session-history event narrowed to the failure signal reconcile needs. */
+export interface ExecutionHistoryEvent {
+  type: string
+  data?: unknown
+}
+
+/** Optional raw-history face used to detect failures of never-opened sessions. */
+export interface HistoryExecutionFace {
+  loadTail(sessionId: string): Promise<{ events: readonly ExecutionHistoryEvent[] } | undefined>
+}
+
+/** The behavior verbs the service invokes on an execution session. */
+export interface SessionDriver {
+  rename(title: string): Promise<unknown>
+  prompt(
+    content: readonly unknown[],
+    mode: 'queue',
+  ): Promise<{ ok: true } | { ok: false; error: unknown }>
+  getSnapshot(): { running: boolean; lastAgentError: string | null; turnEnds: ReadonlyMap<number, number> }
+  subscribe(fn: () => void): () => void
+}
+
+/** Everything the service needs from the runtime. */
+export interface ExecutionEnvironment {
+  sessions: SessionsExecutionFace
+  workspaces: WorkspacesExecutionFace
+  /** Raw-history reader for failure detection of never-opened sessions. */
+  history?: HistoryExecutionFace
+}
+
+/** Outcome events the service emits to the controller. */
+export type ExecutionEvent =
+  | { kind: 'started'; taskId: string; executionId: string; sessionId: string }
+  | { kind: 'settled'; taskId: string; executionId: string; outcome: 'succeeded' | 'failed' | 'cancelled'; error?: string }
+
+/** Human copy for a run failure. */
+function messageOf(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}
+
+/** Whether a `turn/end` payload closed the turn with an error reason. */
+function isErrorTurnEnd(data: unknown): boolean {
+  if (typeof data !== 'object' || data === null) return false
+  const reason = (data as { reason?: unknown }).reason
+  return typeof reason === 'object' && reason !== null
+    && (reason as { kind?: unknown }).kind === 'error'
+}
+
+/**
+ * Run one task to completion (or to a settled failure).
+ *
+ * @param task - the task being executed.
+ * @param execution - the freshly opened execution record (id + start time).
+ * @param onEvent - callback for started/settled events.
+ * @returns resolves when the run settles (or fails to start); never rejects —
+ *   every failure path is reported as a settled event.
+ */
+export class ExecutionService {
+  /** @param env - the runtime faces (real or fake). */
+  constructor(private readonly env: ExecutionEnvironment) {}
+
+  async run(
+    task: TaskRecord,
+    execution: ExecutionRecord,
+    onEvent: (event: ExecutionEvent) => void,
+  ): Promise<void> {
+    try {
+      const sessionId = await this.connectSession()
+      onEvent({ kind: 'started', taskId: task.id, executionId: execution.id, sessionId })
+      const driver = this.driverOf(sessionId)
+      if (driver === undefined) {
+        onEvent({ kind: 'settled', taskId: task.id, executionId: execution.id, outcome: 'failed', error: 'execution session is not ready' })
+        return
+      }
+      // Best-effort rename so the execution is recognizable in the session list.
+      await driver.rename(task.title).catch(() => { /* rename is cosmetic */ })
+      // Baseline the turn counter BEFORE the prompt round-trip: a turn that
+      // completes while prompt is in flight must still advance past this
+      // baseline, or the watch below would never observe it settle.
+      const baseline = driver.getSnapshot().turnEnds.size
+      const accepted = await this.sendPrompt(driver, task)
+      if (!accepted.ok) {
+        onEvent({
+          kind: 'settled', taskId: task.id, executionId: execution.id, outcome: 'failed',
+          error: messageOf(accepted.error),
+        })
+        return
+      }
+      this.watchForSettlement(driver, task.id, execution.id, onEvent, baseline)
+    } catch (error) {
+      onEvent({
+        kind: 'settled', taskId: task.id, executionId: execution.id, outcome: 'failed',
+        error: messageOf(error),
+      })
+    }
+  }
+
+  /**
+   * Inspect a reloaded/background task that was left 'running' and emit a
+   * settled event when its session already finished.
+   *
+   * A session that was never opened keeps a cold conversation snapshot (the
+   * runtime only maintains the window for the staged/current session), so the
+   * settled outcome is decided by the strongest available signal, in order:
+   * 1. the list summary — missing session → cancelled; still running → pending;
+   * 2. a warm conversation snapshot → `lastAgentError` decides failed/succeeded;
+   * 3. the raw history tail (when a history face is wired) — a `turn/end`
+   *    error reason proves failure;
+   * 4. otherwise a finished session counts as succeeded.
+   *
+   * @param task - a task whose latest execution has no endedAt.
+   * @returns a settled event when the session state proves completion, else undefined.
+   */
+  async reconcile(task: TaskRecord): Promise<ExecutionEvent | undefined> {
+    const execution = task.executions[task.executions.length - 1]
+    if (execution === undefined || execution.sessionId === undefined || execution.endedAt !== undefined) return undefined
+    const list = this.env.sessions.list.getSnapshot()
+    // The host list baseline has not arrived yet (page load): a session "not
+    // found" now would be a false cancel. Wait for a later list change.
+    if (list.phase !== 'ready') return undefined
+    const summary = list.byId[execution.sessionId]
+    if (summary === undefined) {
+      return { kind: 'settled', taskId: task.id, executionId: execution.id, outcome: 'cancelled', error: 'execution session no longer exists' }
+    }
+    if (summary.running) return undefined
+    const driver = this.driverOf(execution.sessionId)
+    if (driver !== undefined) {
+      const snapshot = driver.getSnapshot()
+      if (snapshot.turnEnds.size > 0) {
+        const outcome = snapshot.lastAgentError !== null ? 'failed' : 'succeeded'
+        return {
+          kind: 'settled', taskId: task.id, executionId: execution.id, outcome,
+          error: snapshot.lastAgentError ?? undefined,
+        }
+      }
+    }
+    const failed = await this.historyShowsFailure(execution.sessionId)
+    if (failed) {
+      return { kind: 'settled', taskId: task.id, executionId: execution.id, outcome: 'failed', error: 'agent turn failed' }
+    }
+    return { kind: 'settled', taskId: task.id, executionId: execution.id, outcome: 'succeeded' }
+  }
+
+  /** Best-effort failure probe over the raw history tail (false when unavailable). */
+  private async historyShowsFailure(sessionId: string): Promise<boolean> {
+    const history = this.env.history
+    if (history === undefined) return false
+    try {
+      const tail = await history.loadTail(sessionId)
+      if (tail === undefined) return false
+      return tail.events.some(event => event.type === 'turn/end' && isErrorTurnEnd(event.data))
+    } catch (error) {
+      // A failed history read must not block settlement; fall back to success.
+      console.error('[dsh-task-board] history failure probe failed', error)
+      return false
+    }
+  }
+
+  private async connectSession(): Promise<string> {
+    const workspace = this.env.workspaces.list.getSnapshot()
+    const workspaceId = workspace.recentWorkspaceId ?? workspace.items[0]?.workspaceId
+    if (workspaceId === undefined) {
+      throw new Error('no workspace available to run the task in')
+    }
+    return this.env.workspaces.connectWorkspace(workspaceId)
+  }
+
+  private driverOf(sessionId: string): SessionDriver | undefined {
+    return this.env.sessions.binding(sessionId)?.session
+  }
+
+  private async sendPrompt(
+    driver: SessionDriver,
+    task: TaskRecord,
+  ): Promise<{ ok: true } | { ok: false; error: unknown }> {
+    const text = task.prompt.trim() !== '' ? task.prompt : task.title
+    try {
+      const result = await driver.prompt([{ type: 'text', text }], 'queue')
+      return result
+    } catch (error) {
+      return { ok: false, error }
+    }
+  }
+
+  /**
+   * Subscribe to the execution session and settle the run once the accepted
+   * turn completes (turn counter advanced past the acceptance baseline and
+   * the session is no longer running). Never settles while the session is
+   * still running; unsubscribes on settle.
+   */
+  private watchForSettlement(
+    driver: SessionDriver,
+    taskId: string,
+    executionId: string,
+    onEvent: (event: ExecutionEvent) => void,
+    baseline: number,
+  ): void {
+    let settled = false
+    let unsubscribe: () => void = () => {}
+    const check = (): void => {
+      if (settled) return
+      const snapshot = driver.getSnapshot()
+      if (snapshot.running || snapshot.turnEnds.size <= baseline) return
+      settled = true
+      unsubscribe()
+      onEvent({
+        kind: 'settled', taskId, executionId,
+        outcome: snapshot.lastAgentError !== null ? 'failed' : 'succeeded',
+        error: snapshot.lastAgentError ?? undefined,
+      })
+    }
+    unsubscribe = driver.subscribe(check)
+    // A turn can complete during the prompt round-trip (before subscribe):
+    // re-check immediately so a fast turn is never missed.
+    check()
+  }
+}