@linxin666/dsh-client-ui-task-board 0.1.20 → 0.2.0

package/src/power-inhibitor.ts

@@ -0,0 +1,321 @@
+import { spawn as nodeSpawn, spawnSync as nodeSpawnSync, type ChildProcess, type SpawnSyncReturns } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { win32 } from 'node:path'
+import type { PowerPhase, TaskBoardPowerSnapshot } from './protocol.ts'
+
+const RETRY_DELAYS = [1_000, 2_000, 5_000, 10_000, 30_000] as const
+const DARWIN_STABLE_MS = 30_000
+
+const WINDOWS_HELPER = String.raw`
+$source = @'
+using System;
+using System.Runtime.InteropServices;
+public static class DshExecutionState {
+  [DllImport("kernel32.dll", SetLastError = true)]
+  public static extern uint SetThreadExecutionState(uint flags);
+}
+'@
+Add-Type -TypeDefinition $source
+$continuous = [Convert]::ToUInt32('80000000', 16)
+$systemRequired = [uint32]0x00000001
+try {
+  $result = [DshExecutionState]::SetThreadExecutionState($continuous -bor $systemRequired)
+  if ($result -eq 0) { throw 'SetThreadExecutionState failed' }
+  [Console]::Out.WriteLine('READY')
+  [Console]::Out.Flush()
+  while ([Console]::In.ReadLine() -ne $null) { }
+} finally {
+  [void][DshExecutionState]::SetThreadExecutionState($continuous)
+}
+`
+
+const LINUX_HELPER = String.raw`
+process.stdout.write('READY\n')
+process.stdin.resume()
+`
+
+const LINUX_INHIBIT_PATHS = ['/usr/bin/systemd-inhibit', '/bin/systemd-inhibit'] as const
+
+export interface PowerReasons {
+  runningSessions: number
+  armedSchedules: number
+  sessionStateKnown: boolean
+}
+
+export interface SpawnOptions {
+  shell: false
+  windowsHide: boolean
+  stdio: ['pipe', 'pipe', 'pipe'] | ['ignore', 'ignore', 'ignore']
+}
+
+export type SpawnLike = (file: string, args: readonly string[], options: SpawnOptions) => ChildProcess
+export type SpawnSyncLike = (
+  file: string,
+  args: readonly string[],
+  options: { stdio: 'ignore'; timeout: number; windowsHide: boolean },
+) => Pick<SpawnSyncReturns<Buffer>, 'status' | 'error'>
+
+export interface PowerInhibitorOptions {
+  platform?: NodeJS.Platform
+  pid?: number
+  env?: NodeJS.ProcessEnv
+  spawn?: SpawnLike
+  spawnSync?: SpawnSyncLike
+  exists?: typeof existsSync
+  execPath?: string
+  setTimeout?: typeof globalThis.setTimeout
+  clearTimeout?: typeof globalThis.clearTimeout
+}
+
+export class PowerInhibitor {
+  private readonly listeners = new Set<() => void>()
+  private enabled = false
+  private reasons: PowerReasons = { runningSessions: 0, armedSchedules: 0, sessionStateKnown: false }
+  private phase: PowerPhase = 'disabled'
+  private child: ChildProcess | undefined
+  private retry: ReturnType<typeof setTimeout> | undefined
+  private retryReset: ReturnType<typeof setTimeout> | undefined
+  private retryIndex = 0
+  private lastError: string | undefined
+  private stopping = false
+  private readonly platform: NodeJS.Platform
+  private readonly pid: number
+  private readonly env: NodeJS.ProcessEnv
+  private readonly spawn: SpawnLike
+  private readonly spawnSync: SpawnSyncLike
+  private readonly exists: typeof existsSync
+  private readonly execPath: string
+  private readonly timer: typeof globalThis.setTimeout
+  private readonly clearTimer: typeof globalThis.clearTimeout
+  private linuxProbe: { executable?: string; available: boolean } | undefined
+
+  constructor(options: PowerInhibitorOptions = {}) {
+    this.platform = options.platform ?? process.platform
+    this.pid = options.pid ?? process.pid
+    this.env = options.env ?? process.env
+    this.spawn = options.spawn ?? ((file, args, spawnOptions) => nodeSpawn(file, [...args], spawnOptions))
+    this.spawnSync = options.spawnSync ?? ((file, args, spawnOptions) => nodeSpawnSync(file, [...args], spawnOptions))
+    this.exists = options.exists ?? existsSync
+    this.execPath = options.execPath ?? process.execPath
+    this.timer = options.setTimeout ?? globalThis.setTimeout
+    this.clearTimer = options.clearTimeout ?? globalThis.clearTimeout
+  }
+
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled
+    this.sync()
+    this.emit()
+  }
+
+  updateReasons(reasons: PowerReasons): void {
+    this.reasons = reasons
+    this.sync()
+    this.emit()
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  snapshot(): TaskBoardPowerSnapshot {
+    return {
+      platform: this.platform,
+      phase: this.phase,
+      enabled: this.enabled,
+      ...this.reasons,
+      ...(this.lastError === undefined ? {} : { lastError: this.lastError }),
+    }
+  }
+
+  dispose(): void {
+    this.enabled = false
+    this.release()
+    this.phase = 'disabled'
+    this.emit()
+    this.listeners.clear()
+  }
+
+  private desired(): boolean {
+    return this.enabled && (!this.reasons.sessionStateKnown || this.reasons.runningSessions > 0 || this.reasons.armedSchedules > 0)
+  }
+
+  private sync(): void {
+    if (!this.enabled) {
+      this.release()
+      this.phase = 'disabled'
+      return
+    }
+    if (this.platform !== 'darwin' && this.platform !== 'win32' && this.platform !== 'linux') {
+      this.release()
+      this.phase = 'unsupported'
+      return
+    }
+    if (this.platform === 'linux' && this.linuxSystemdInhibit() === undefined) {
+      this.release()
+      this.phase = 'unsupported'
+      return
+    }
+    if (!this.desired()) {
+      this.release()
+      this.phase = 'idle'
+      return
+    }
+    if (this.child === undefined && this.retry === undefined) this.acquire()
+  }
+
+  private acquire(): void {
+    this.phase = 'acquiring'
+    this.emit()
+    this.stopping = false
+    try {
+      const child = this.spawnCommand()
+      this.child = child
+      let ready = false
+      let stderr = ''
+      if (this.platform === 'darwin') {
+        child.once('spawn', () => {
+          ready = true
+          this.markReady(child)
+        })
+      }
+      child.stdout?.on('data', (chunk: Buffer) => {
+        if (!ready && chunk.toString('utf8').includes('READY')) {
+          ready = true
+          this.markReady(child)
+        }
+      })
+      child.stderr?.on('data', (chunk: Buffer) => {
+        stderr = `${stderr}${chunk.toString('utf8')}`.slice(-2_000)
+      })
+      child.on('error', error => { this.fail(error, child) })
+      child.on('exit', (code, signal) => {
+        if (this.child !== child) return
+        this.child = undefined
+        if (this.stopping || !this.desired()) return
+        const detail = stderr.trim()
+        this.fail(new Error(`power helper exited (${String(code ?? signal ?? 'unknown')})${detail === '' ? '' : `: ${detail}`}`))
+      })
+    } catch (error) {
+      this.fail(error)
+    }
+  }
+
+  private markReady(child: ChildProcess): void {
+    if (this.child !== child || !this.desired()) return
+    this.phase = 'active'
+    if (this.platform === 'darwin') {
+      this.retryReset = this.timer(() => {
+        this.retryReset = undefined
+        if (this.child === child && this.desired()) this.retryIndex = 0
+      }, DARWIN_STABLE_MS)
+    } else {
+      this.retryIndex = 0
+    }
+    this.lastError = undefined
+    this.emit()
+  }
+
+  private fail(error: unknown, source?: ChildProcess): void {
+    if (source !== undefined && this.child !== source) return
+    this.clearRetryReset()
+    this.lastError = error instanceof Error ? error.message : String(error)
+    this.phase = 'error'
+    this.emit()
+    const child = this.child
+    this.child = undefined
+    child?.stdin?.end()
+    child?.kill()
+    if (!this.desired() || this.retry !== undefined) return
+    const delay = RETRY_DELAYS[Math.min(this.retryIndex, RETRY_DELAYS.length - 1)]
+    this.retryIndex += 1
+    this.retry = this.timer(() => {
+      this.retry = undefined
+      if (this.desired()) this.acquire()
+    }, delay)
+  }
+
+  private release(): void {
+    this.clearRetryReset()
+    if (this.retry !== undefined) {
+      this.clearTimer(this.retry)
+      this.retry = undefined
+    }
+    this.lastError = undefined
+    const child = this.child
+    this.child = undefined
+    if (child === undefined) return
+    this.stopping = true
+    if (this.platform === 'win32' || this.platform === 'linux') {
+      child.stdin?.end()
+      const force = this.timer(() => { if (child.exitCode === null) child.kill() }, 1_000)
+      child.once('exit', () => { this.clearTimer(force) })
+    } else {
+      child.kill('SIGTERM')
+    }
+  }
+
+  private clearRetryReset(): void {
+    if (this.retryReset === undefined) return
+    this.clearTimer(this.retryReset)
+    this.retryReset = undefined
+  }
+
+  private windowsPowerShell(): string {
+    const root = this.env.SystemRoot
+    if (root === undefined || root.trim() === '') throw new Error('SystemRoot is unavailable')
+    if (!win32.isAbsolute(root)) throw new Error('SystemRoot is not an absolute path')
+    return win32.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe')
+  }
+
+  private linuxSystemdInhibit(): string | undefined {
+    if (this.linuxProbe !== undefined) return this.linuxProbe.available ? this.linuxProbe.executable : undefined
+    const executable = LINUX_INHIBIT_PATHS.find(path => this.exists(path))
+    if (executable === undefined) {
+      this.linuxProbe = { available: false }
+      return undefined
+    }
+    const probe = this.spawnSync(executable, ['--list', '--no-pager'], {
+      stdio: 'ignore',
+      timeout: 2_000,
+      windowsHide: true,
+    })
+    this.linuxProbe = { executable, available: probe.status === 0 && probe.error === undefined }
+    return this.linuxProbe.available ? executable : undefined
+  }
+
+  private spawnCommand(): ChildProcess {
+    if (this.platform === 'darwin') {
+      return this.spawn('/usr/bin/caffeinate', ['-i', '-w', String(this.pid)], {
+        shell: false,
+        windowsHide: false,
+        stdio: ['ignore', 'ignore', 'ignore'],
+      })
+    }
+    if (this.platform === 'linux') {
+      const executable = this.linuxSystemdInhibit()
+      if (executable === undefined) throw new Error('systemd-inhibit is unavailable')
+      return this.spawn(executable, [
+        '--what=idle',
+        '--who=DeepSeek Harness task board',
+        '--why=DSH sessions are running or schedules are armed',
+        '--mode=block',
+        '--',
+        this.execPath,
+        '-e',
+        LINUX_HELPER,
+      ], { shell: false, windowsHide: false, stdio: ['pipe', 'pipe', 'pipe'] })
+    }
+    return this.spawn(this.windowsPowerShell(), ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', WINDOWS_HELPER], {
+      shell: false,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+  }
+
+  private emit(): void {
+    for (const listener of [...this.listeners]) listener()
+  }
+}
+
+export { LINUX_HELPER, LINUX_INHIBIT_PATHS, WINDOWS_HELPER }

package/src/protocol.ts

@@ -0,0 +1,213 @@
+import type { TaskUpdatePatch } from './core/use-cases/task-update.ts'
+import { isTaskPermission, isTaskStatus, type NewTaskInput, type TaskRecord, type TaskStatus } from './core/tasks.ts'
+import { parseLedger } from './core/store.ts'
+
+export const TASK_BOARD_SCHEMA_VERSION = 2 as const
+export const TASK_BOARD_API_PREFIX = '/api/task-board'
+
+export type PowerPhase = 'disabled' | 'idle' | 'acquiring' | 'active' | 'error' | 'unsupported'
+
+export interface TaskBoardPowerSnapshot {
+  platform: string
+  phase: PowerPhase
+  enabled: boolean
+  runningSessions: number
+  armedSchedules: number
+  sessionStateKnown: boolean
+  lastError?: string
+}
+
+export interface TaskBoardSchedulerSnapshot {
+  timeZone: string
+  /** Opaque identity of the current Host ledger generation. */
+  ledgerId?: string
+  lastTickAt?: number
+  error?: string
+}
+
+export interface TaskBoardSnapshot {
+  schemaVersion: typeof TASK_BOARD_SCHEMA_VERSION
+  revision: number
+  tasks: TaskRecord[]
+  scheduler: TaskBoardSchedulerSnapshot
+  power: TaskBoardPowerSnapshot
+}
+
+export type TaskBoardAction =
+  | { kind: 'import'; sourceId: string; tasks: TaskRecord[] }
+  | { kind: 'create'; id: string; input: NewTaskInput }
+  | { kind: 'update'; taskId: string; patch: TaskUpdatePatch }
+  | { kind: 'delete'; taskId: string }
+  | { kind: 'move'; taskId: string; status: TaskStatus }
+  | { kind: 'archive'; taskId: string }
+  | { kind: 'restore'; taskId: string }
+  | { kind: 'set-schedule'; taskId: string; patch: { enabled?: boolean; cron?: string } }
+  | { kind: 'run'; taskId: string }
+  | { kind: 'rerun'; taskId: string }
+
+export interface TaskBoardActionEnvelope {
+  requestId: string
+  action: TaskBoardAction
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  return Object.keys(value).every(key => allowed.includes(key))
+}
+
+function optionalString(value: unknown): boolean {
+  return value === undefined || typeof value === 'string'
+}
+
+const FORBIDDEN_IMPORT_FIELDS = new Set(['args', 'command', 'executable', 'powershell', 'shell'])
+
+function hasForbiddenImportField(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(hasForbiddenImportField)
+  const row = record(value)
+  if (row === undefined) return false
+  return Object.entries(row).some(([key, nested]) => FORBIDDEN_IMPORT_FIELDS.has(key.toLowerCase()) || hasForbiddenImportField(nested))
+}
+
+function optionalFiniteNumber(value: unknown): boolean {
+  return value === undefined || (typeof value === 'number' && Number.isFinite(value))
+}
+
+function validImportedKnownFields(value: Record<string, unknown>): boolean {
+  if (value.schedule !== undefined) {
+    const schedule = record(value.schedule)
+    if (schedule === undefined || typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
+    if (!optionalFiniteNumber(schedule.nextRunAt) || !optionalFiniteNumber(schedule.lastTriggeredAt)) return false
+  }
+  if (value.executions !== undefined) {
+    if (!Array.isArray(value.executions)) return false
+    for (const item of value.executions) {
+      const execution = record(item)
+      if (execution === undefined || typeof execution.id !== 'string' || !optionalString(execution.sessionId)) return false
+      if (typeof execution.startedAt !== 'number' || !Number.isFinite(execution.startedAt)) return false
+      if (!optionalFiniteNumber(execution.endedAt) || !optionalString(execution.error)) return false
+      if (execution.result !== undefined && !['succeeded', 'failed', 'cancelled'].includes(String(execution.result))) return false
+    }
+  }
+  return true
+}
+
+function importedTask(value: unknown): TaskRecord | undefined {
+  const input = record(value)
+  if (input === undefined || hasForbiddenImportField(input) || !validImportedKnownFields(input)) return undefined
+  const task = parseLedger(JSON.stringify([value]))[0]
+  if (task === undefined) return undefined
+  return {
+    id: task.id,
+    title: task.title,
+    description: task.description,
+    prompt: task.prompt,
+    status: task.status,
+    createdAt: task.createdAt,
+    updatedAt: task.updatedAt,
+    executions: task.executions.map(execution => ({
+      id: execution.id,
+      sessionId: execution.sessionId,
+      startedAt: execution.startedAt,
+      endedAt: execution.endedAt,
+      result: execution.result,
+      error: execution.error,
+    })),
+    ...(task.schedule === undefined ? {} : {
+      schedule: {
+        enabled: task.schedule.enabled,
+        cron: task.schedule.cron,
+        nextRunAt: task.schedule.nextRunAt,
+        lastTriggeredAt: task.schedule.lastTriggeredAt,
+      },
+    }),
+    ...(task.workspaceId === undefined ? {} : { workspaceId: task.workspaceId }),
+    ...(task.mode === undefined ? {} : { mode: task.mode }),
+    ...(task.permission === undefined ? {} : { permission: task.permission }),
+    ...(task.archivedAt === undefined ? {} : { archivedAt: task.archivedAt }),
+  }
+}
+
+function createInput(value: unknown): value is NewTaskInput {
+  const input = record(value)
+  if (input === undefined || !exactKeys(input, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission', 'schedule'])) return false
+  if (typeof input.title !== 'string' || typeof input.description !== 'string' || typeof input.prompt !== 'string') return false
+  if (!optionalString(input.workspaceId) || !optionalString(input.mode)) return false
+  if (input.permission !== undefined && !isTaskPermission(input.permission)) return false
+  if (input.schedule !== undefined) {
+    const schedule = record(input.schedule)
+    if (schedule === undefined || !exactKeys(schedule, ['enabled', 'cron'])) return false
+    if (typeof schedule.enabled !== 'boolean' || typeof schedule.cron !== 'string') return false
+  }
+  return true
+}
+
+function updatePatch(value: unknown): boolean {
+  const patch = record(value)
+  if (patch === undefined || !exactKeys(patch, ['title', 'description', 'prompt', 'workspaceId', 'mode', 'permission'])) return false
+  for (const key of ['title', 'description', 'prompt', 'workspaceId', 'mode'] as const) {
+    if (!optionalString(patch[key])) return false
+  }
+  return patch.permission === undefined || isTaskPermission(patch.permission)
+}
+
+function schedulePatch(value: unknown): boolean {
+  const patch = record(value)
+  return patch !== undefined
+    && exactKeys(patch, ['enabled', 'cron'])
+    && (patch.enabled === undefined || typeof patch.enabled === 'boolean')
+    && (patch.cron === undefined || typeof patch.cron === 'string')
+}
+
+export function parseActionEnvelope(value: unknown): TaskBoardActionEnvelope | undefined {
+  const envelope = record(value)
+  if (envelope === undefined || !exactKeys(envelope, ['requestId', 'action'])) return undefined
+  if (typeof envelope.requestId !== 'string' || envelope.requestId.trim() === '' || envelope.requestId.length > 256) return undefined
+  const action = record(envelope.action)
+  if (action === undefined || typeof action.kind !== 'string') return undefined
+  const taskId = typeof action.taskId === 'string' && action.taskId !== '' ? action.taskId : undefined
+  switch (action.kind) {
+    case 'import':
+      if (!exactKeys(action, ['kind', 'sourceId', 'tasks'])) return undefined
+      if (typeof action.sourceId !== 'string' || action.sourceId === '' || !Array.isArray(action.tasks)) return undefined
+      {
+        const tasks = action.tasks.map(importedTask)
+        return tasks.every((task): task is TaskRecord => task !== undefined)
+          ? { requestId: envelope.requestId, action: { kind: 'import', sourceId: action.sourceId, tasks } }
+          : undefined
+      }
+    case 'create':
+      if (!exactKeys(action, ['kind', 'id', 'input'])) return undefined
+      return typeof action.id === 'string' && action.id !== '' && createInput(action.input)
+        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'create' }> }
+        : undefined
+    case 'update':
+      if (!exactKeys(action, ['kind', 'taskId', 'patch'])) return undefined
+      return taskId !== undefined && updatePatch(action.patch)
+        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'update' }> }
+        : undefined
+    case 'set-schedule':
+      if (!exactKeys(action, ['kind', 'taskId', 'patch'])) return undefined
+      return taskId !== undefined && schedulePatch(action.patch)
+        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'set-schedule' }> }
+        : undefined
+    case 'move':
+      if (!exactKeys(action, ['kind', 'taskId', 'status'])) return undefined
+      return taskId !== undefined && isTaskStatus(action.status)
+        ? { requestId: envelope.requestId, action: action as unknown as Extract<TaskBoardAction, { kind: 'move' }> }
+        : undefined
+    case 'delete':
+    case 'archive':
+    case 'restore':
+    case 'run':
+    case 'rerun':
+      if (!exactKeys(action, ['kind', 'taskId'])) return undefined
+      return taskId === undefined ? undefined : { requestId: envelope.requestId, action: action as TaskBoardAction }
+    default:
+      return undefined
+  }
+}

package/lib/types/core/scheduler.d.ts

@@ -1,70 +0,0 @@
-import type { TaskRecord } from './tasks.ts';
-/** Everything the scheduler needs from its host (the board controller). */
-export interface SchedulerDeps {
-    /** Read the current task ledger (the controller snapshot). */
-    tasks(): readonly TaskRecord[];
-    /**
-     * Re-sync the task ledger from its persisted source before the tick decides
-     * what is due. The wiring passes the controller's store reload so a task
-     * deleted elsewhere can never be fired from a stale in-memory copy.
-     * Optional: absent in pure in-memory harnesses.
-     */
-    refresh?: () => void;
-    /** Clock; defaults to Date.now in the controller wiring. */
-    now(): number;
-    /** Trigger one task's real execution (the controller's runTask); resolves
-     *  true when the run was accepted, false when rejected (e.g. the task is
-     *  already running). */
-    runTask(id: string): Promise<boolean>;
-    /** Persist a rolled-forward schedule (next due + this trigger instant). */
-    applySchedule(id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined): void;
-    /** Tick cadence; defaults to 60_000 ms. */
-    tickMs?: number;
-    /**
-     * Gate: while false the tick no-ops (e.g. the session list baseline has not
-     * arrived on page load, so executions would fail). Defaults to always ready.
-     */
-    ready?: () => boolean;
-    /** Environment listeners for tab-visibility recovery (browser only). */
-    environment?: {
-        addEventListener(type: 'visibilitychange', listener: () => void): void;
-        removeEventListener(type: 'visibilitychange', listener: () => void): void;
-    };
-}
-/**
- * The schedule heartbeat (see module doc). `tick` is public so tests and
- * callers can drive a check without waiting for the interval.
- */
-export declare class SchedulerService {
-    private readonly deps;
-    private timer;
-    private environmentListener;
-    private disposed;
-    private started;
-    /** Cron expressions that matched no instant in the scan window, per task —
-     *  remembered so a never-matching rule is not re-scanned on every tick. */
-    private readonly unmatchableRepair;
-    /** @param deps - tasks/clock/trigger/apply faces (see {@link SchedulerDeps}). */
-    constructor(deps: SchedulerDeps);
-    /**
-     * Start ticking: one immediate check (catch-up after reload) + the interval.
-     * Single-instance: a second start while already armed is a no-op, so a
-     * re-entrant mount can never stack a duplicate timer.
-     */
-    start(): void;
-    /**
-     * Stop ticking and drop listeners (idempotent). Preferred shutdown verb for
-     * callers that treat the scheduler as a controlled ticker; `dispose` is an
-     * alias.
-     */
-    stop(): void;
-    /** Stop ticking and drop listeners (idempotent). */
-    dispose(): void;
-    /**
-     * Check every enabled schedule and trigger the due ones. Idempotent per
-     * task per tick: the schedule is rolled forward only after runTask accepts
-     * the run, so a rejected run keeps its due slot and is retried on the next
-     * tick instead of being silently dropped.
-     */
-    tick(): Promise<void>;
-}