dsh-taskboard 0.1.0

package/src/host/scheduler.ts

@@ -0,0 +1,107 @@
+/**
+ * Host-side cron scheduler: one tick per minute over the ledger's scheduled
+ * tasks. A due task (nextRunAt reached, not running, not trashed) first has
+ * its next run advanced to the next cron match — then it executes through
+ * the same path as the manual button. Missed windows (host was down, tab
+ * closed — irrelevant here, this is the host process) simply advance: a
+ * nextRunAt more than one window in the past is skipped, not caught up.
+ *
+ * @module dsh-taskboard/host/scheduler
+ */
+import { nextCronTime, parseCron, type TaskLedger } from '../shared/protocol.ts'
+import type { ExecutionService } from './execution.ts'
+import type { TaskStore } from './store.ts'
+
+/** Tick cadence. */
+const TICK_MS = 60_000
+
+/** A due window older than this is skipped (missed while the host was down). */
+const SKIP_AFTER_MS = 5 * 60_000
+
+/** Everything the scheduler needs. */
+export interface SchedulerDeps {
+  store: TaskStore
+  execution: Pick<ExecutionService, 'run'>
+  now: () => number
+  /** Timer face (injectable for tests). */
+  timers?: {
+    setInterval(fn: () => void, ms: number): unknown
+    clearInterval(handle: unknown): void
+  }
+}
+
+/**
+ * The cron scheduler.
+ */
+export class SchedulerService {
+  private handle: unknown
+
+  /** @param deps - store + execution + clock. */
+  constructor(private readonly deps: SchedulerDeps) {}
+
+  /** Start ticking. */
+  start(): void {
+    const timers = this.deps.timers ?? {
+      setInterval: (fn: () => void, ms: number) => setInterval(fn, ms),
+      clearInterval: (handle: unknown) => clearInterval(handle as ReturnType<typeof setInterval>),
+    }
+    this.handle = timers.setInterval(() => { void this.tick() }, TICK_MS)
+    // Catch up promptly on host restart: run one tick soon after start.
+    setTimeout(() => { void this.tick() }, 3_000)
+  }
+
+  /** Stop ticking. */
+  dispose(): void {
+    if (this.handle === undefined) return
+    const timers = this.deps.timers ?? { clearInterval: (h: unknown) => clearInterval(h as ReturnType<typeof setInterval>) }
+    timers.clearInterval(this.handle)
+    this.handle = undefined
+  }
+
+  /** One scheduler pass (exported for tests). */
+  async tick(): Promise<void> {
+    const now = this.deps.now()
+    const ledger: TaskLedger = this.deps.store.snapshot()
+    for (const task of ledger.tasks) {
+      if (task.execution.mode !== 'scheduled' || task.execution.cron === undefined) continue
+      if (task.execution.nextRunAt === undefined) continue
+      if (task.status === 'in_progress' || task.trashedAt !== undefined) continue
+      if (task.execution.nextRunAt > now) continue
+      const missed = now - task.execution.nextRunAt > SKIP_AFTER_MS
+
+      // Advance the schedule FIRST (idempotent under re-ticks), then run
+      // unless the window was missed entirely.
+      await this.advance(task.id, now)
+      if (missed) continue
+      const lastTriggeredAt = task.execution.nextRunAt
+      await this.markTriggered(task.id, lastTriggeredAt)
+      await this.deps.execution.run(task.id, 'scheduled').catch(error => {
+        console.error('[dsh-taskboard] scheduled run failed:', error)
+      })
+    }
+  }
+
+  /** Recompute and persist the next run for one scheduled task. */
+  private async advance(taskId: string, now: number): Promise<void> {
+    await this.deps.store.mutate('task-updated', (ledger) => {
+      const task = ledger.tasks.find(t => t.id === taskId)
+      if (task === undefined || task.execution.cron === undefined) return undefined
+      const match = parseCron(task.execution.cron)
+      const next = match === null ? undefined : nextCronTime(match, now) ?? undefined
+      if (next === undefined) return undefined
+      task.execution.nextRunAt = next
+      return [task]
+    })
+  }
+
+  /** Record the trigger instant on the task. */
+  private async markTriggered(taskId: string, at: number | undefined): Promise<void> {
+    if (at === undefined) return
+    await this.deps.store.mutate('task-updated', (ledger) => {
+      const task = ledger.tasks.find(t => t.id === taskId)
+      if (task === undefined) return undefined
+      task.execution.lastTriggeredAt = at
+      return [task]
+    })
+  }
+}

package/src/host/sdk.ts

@@ -0,0 +1,200 @@
+/**
+ * Self-contained replacements for the three @deepseek-ai runtime imports the
+ * host half used to take from npm-mirror SDK packages (dsh-home-paths,
+ * dsh-llm/brand, dsh-tools' defineTool).
+ *
+ * Why: a published copy must never resolve `@deepseek-ai/dsh-tools` from the
+ * profile's node_modules — an npm-mirror dsh-tools there shadows the
+ * CLI-internal build for the WHOLE base layer, and the agent loop's private
+ * scheduler symbol then misses (`Cannot read properties of undefined
+ * (reading 'prepare')` on every tool call). Everything here is a pure,
+ * structure-compatible reimplementation of the exact behavior we relied on:
+ *
+ * - `dshHomePath` mirrors `join(resolve(env.DSH_HOME ?? ~/.dsh), ...segments)`;
+ * - `MessageId` is the identity brand the SDK applies at runtime;
+ * - `defineTool` compiles our author-facing parameter specs into the same
+ *   raw JSON-Schema subset the registry expects (object/properties/required/
+ *   additionalProperties/scalars; the `json` node compiles to an
+ *   annotation-only schema) and pre-validates model arguments the same way.
+ *
+ * @module dsh-taskboard/host/sdk
+ */
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/** The ledger file's parent: the DSH user home (DSH_HOME overrides). */
+export function dshHomePath(...segments: string[]): string {
+  const override = process.env.DSH_HOME
+  const home = resolve(override !== undefined && override.length > 0 ? override : join(homedir(), '.dsh'))
+  return join(home, ...segments)
+}
+
+/** Identity brand — runtime no-op, exactly like the SDK's MessageId(). */
+export function MessageId(id: string): string {
+  return id
+}
+
+/** Author-facing scalar spec. */
+interface ScalarSpec {
+  readonly type: 'string' | 'number' | 'integer' | 'boolean' | 'null'
+  readonly description?: string
+  readonly enum?: readonly unknown[]
+  readonly const?: unknown
+}
+
+/** Author-facing object spec (additionalProperties is mandatory). */
+interface ObjectSpec {
+  readonly type: 'object'
+  readonly additionalProperties: boolean
+  readonly description?: string
+  readonly properties?: Readonly<Record<string, ValueSpec>>
+}
+
+/** Author-facing value spec. */
+type ValueSpec = ScalarSpec | ObjectSpec | { readonly type: 'json' } | { readonly type: 'array'; readonly items?: ValueSpec; readonly description?: string }
+
+/** Author-facing parameter entry (a value spec plus top-level required). */
+type ParameterSpec = ValueSpec & { readonly required?: boolean }
+
+/** Raw JSON-Schema subset node. */
+type RawSchema = Record<string, unknown>
+
+/** Compile one value spec to the raw subset (json → annotation-only). */
+function compileValue(spec: ValueSpec): RawSchema {
+  const node: RawSchema = {}
+  const description = (spec as { description?: string }).description
+  if (typeof description === 'string' && description.length > 0) node.description = description
+  const type = (spec as { type?: string }).type
+  if (type === undefined || type === 'json') return node
+  if (type === 'object') {
+    const objectSpec = spec as ObjectSpec
+    node.type = 'object'
+    node.additionalProperties = objectSpec.additionalProperties
+    if (objectSpec.properties !== undefined) node.properties = compilePropertyMap(objectSpec.properties).properties
+    return node
+  }
+  if (type === 'array') {
+    node.type = 'array'
+    const items = (spec as { items?: ValueSpec }).items
+    if (items !== undefined) node.items = compileValue(items)
+    return node
+  }
+  node.type = type
+  const enumValues = (spec as ScalarSpec).enum
+  if (enumValues !== undefined) node.enum = [...enumValues]
+  const constValue = (spec as ScalarSpec).const
+  if (constValue !== undefined) node.const = constValue
+  return node
+}
+
+/** Compile a property map: properties + collected required list. */
+function compilePropertyMap(spec: Readonly<Record<string, ParameterSpec>>): { properties: Record<string, RawSchema>; required?: string[] } {
+  const properties: Record<string, RawSchema> = {}
+  const required: string[] = []
+  for (const [name, entry] of Object.entries(spec)) {
+    const { required: isRequired, ...valueSpec } = entry as ParameterSpec & Record<string, unknown>
+    properties[name] = compileValue(valueSpec as ValueSpec)
+    if (isRequired === true) required.push(name)
+  }
+  return required.length > 0 ? { properties, required } : { properties }
+}
+
+/** Does a JS value match a raw-subset scalar type? */
+function matchesScalarType(value: unknown, type: string): boolean {
+  switch (type) {
+    case 'string': return typeof value === 'string'
+    case 'number': return typeof value === 'number'
+    case 'integer': return typeof value === 'number' && Number.isInteger(value)
+    case 'boolean': return typeof value === 'boolean'
+    case 'null': return value === null
+    default: return true
+  }
+}
+
+/** Validate a value against the compiled subset; returns path-qualified violations. */
+function validateValue(schema: RawSchema, value: unknown, path: string): string[] {
+  if (typeof schema.type !== 'string' || schema.type.length === 0) return []
+  if (schema.type === 'object') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return [`${path} must be an object`]
+    const violations: string[] = []
+    const present = value as Record<string, unknown>
+    for (const key of (schema.required as string[] | undefined) ?? []) {
+      if (!(key in present)) violations.push(`${path}.${key} is required`)
+    }
+    if (schema.additionalProperties === false) {
+      const known = new Set(Object.keys((schema.properties as Record<string, RawSchema> | undefined) ?? {}))
+      for (const key of Object.keys(present)) {
+        if (!known.has(key)) violations.push(`${path}.${key} is not a declared property`)
+      }
+    }
+    for (const [key, child] of Object.entries((schema.properties as Record<string, RawSchema> | undefined) ?? {})) {
+      if (key in present) violations.push(...validateValue(child, present[key], `${path}.${key}`))
+    }
+    return violations
+  }
+  if (schema.type === 'array') {
+    if (!Array.isArray(value)) return [`${path} must be an array`]
+    const violations: string[] = []
+    const items = schema.items as RawSchema | undefined
+    if (items !== undefined) {
+      value.forEach((item, index) => { violations.push(...validateValue(items, item, `${path}[${index}]`)) })
+    }
+    return violations
+  }
+  return matchesScalarType(value, schema.type) ? [] : [`${path} must be ${schema.type}`]
+}
+
+/** Options shape we consume (a structural subset of the SDK's defineTool). */
+export interface DefineToolOptions<A, V> {
+  readonly name: string
+  readonly description: string
+  readonly parameters: Readonly<Record<string, ParameterSpec>>
+  readonly output: {
+    readonly schema: { readonly type: 'json' }
+    render(args: A, value: V): Array<{ type: 'text'; text: string }>
+  }
+  execute(args: A, exec: unknown): Promise<V>
+}
+
+/** A registry-ready tool definition (structure-compatible with the SDK's). */
+export interface ToolDefinition<A = unknown, V = unknown> {
+  readonly name: string
+  readonly description: string
+  readonly parameters: RawSchema
+  readonly output: {
+    readonly schema: RawSchema
+    render(args: A, value: V): Array<{ type: 'text'; text: string }>
+  }
+  execute(args: A, exec: unknown): Promise<V>
+}
+
+/**
+ * Define a first-party tool: compile the parameter spec, pre-validate
+ * arguments (message format matches the SDK's ToolArgsError), and pass
+ * through the execution.
+ */
+export function defineTool<A extends Record<string, unknown>, V>(options: DefineToolOptions<A, V>): ToolDefinition<A, V> {
+  const compiled = compilePropertyMap(options.parameters as Readonly<Record<string, ParameterSpec>>)
+  const parameters: RawSchema = { type: 'object', properties: compiled.properties }
+  if (compiled.required !== undefined) parameters.required = compiled.required
+  const userExecute = options.execute
+  return {
+    name: options.name,
+    description: options.description,
+    parameters,
+    output: {
+      // The SDK compiles the `json` node to an annotation-only schema.
+      schema: {},
+      render(args, value) {
+        return options.output.render(args, value)
+      },
+    },
+    async execute(args, exec) {
+      const violations = validateValue(parameters, args, 'arguments')
+      if (violations.length > 0) {
+        throw new Error(`Error: invalid arguments: ${violations.join('; ')}`)
+      }
+      return userExecute(args, exec)
+    },
+  }
+}

package/src/host/store.ts

@@ -0,0 +1,139 @@
+/**
+ * Host-side task ledger: one JSON file under the DSH home, mutated through a
+ * serial write queue, published as immutable snapshots with a global
+ * monotonic revision. Change subscribers (P2: SSE route) observe every
+ * committed mutation.
+ *
+ * @module dsh-taskboard/host/store
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import {
+  LEDGER_SCHEMA_VERSION,
+  emptyLedger,
+  type TaskLedger,
+  type TaskRecord,
+} from '../shared/protocol.ts'
+
+/** One committed ledger mutation, handed to change subscribers. */
+export interface LedgerChange {
+  /** Revision after the mutation. */
+  revision: number
+  /** The mutated tasks, if any (a comment purge may touch none). */
+  tasks: readonly TaskRecord[]
+  /** What kind of mutation this was (for SSE event naming later). */
+  kind: 'task-created' | 'task-updated' | 'task-moved' | 'task-deleted' | 'comment-added' | 'execution-recorded'
+}
+
+/** Options for {@link TaskStore}. */
+export interface TaskStoreOptions {
+  /** Absolute ledger file path. */
+  file: string
+}
+
+/**
+ * The durable ledger. All mutations run through {@link mutate}, which:
+ * validates the resulting document, bumps the global revision, persists
+ * atomically (temp file + rename), and only then notifies subscribers.
+ */
+export class TaskStore {
+  private readonly file: string
+  private ledger: TaskLedger = emptyLedger()
+  private readonly subscribers = new Set<(change: LedgerChange) => void>()
+  private queue: Promise<unknown> = Promise.resolve()
+  private loaded = false
+
+  /** @param options - file location. */
+  constructor(options: TaskStoreOptions) {
+    this.file = options.file
+  }
+
+  /** Load (once) from disk; a missing file starts empty; a corrupt file is quarantined, not thrown. */
+  async load(): Promise<void> {
+    if (this.loaded) return
+    try {
+      const raw = await readFile(this.file, 'utf8')
+      const parsed = JSON.parse(raw) as TaskLedger
+      if (typeof parsed.revision === 'number' && Array.isArray(parsed.tasks)) {
+        this.ledger = { schemaVersion: LEDGER_SCHEMA_VERSION, revision: parsed.revision, tasks: parsed.tasks }
+      }
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code
+      if (code !== 'ENOENT') {
+        // Quarantine a corrupt ledger: rename it aside, start fresh. Never
+        // take the host down over ledger damage.
+        try {
+          await rename(this.file, `${this.file}.corrupt-${Date.now()}`)
+        } catch { /* best effort */ }
+      }
+    }
+    this.loaded = true
+  }
+
+  /** The current immutable snapshot. */
+  snapshot(): TaskLedger {
+    return this.ledger
+  }
+
+  /** Find a task by id. */
+  get(id: string): TaskRecord | undefined {
+    return this.ledger.tasks.find(t => t.id === id)
+  }
+
+  /** Subscribe to committed changes; returns the unsubscribe. */
+  subscribe(fn: (change: LedgerChange) => void): () => void {
+    this.subscribers.add(fn)
+    return () => this.subscribers.delete(fn)
+  }
+
+  /**
+   * Run one mutation inside the serial queue. The mutator works on a
+   * structured clone; returning `undefined` aborts with no write.
+   * @param kind - change kind for subscribers.
+   * @param mutator - receives the cloned ledger; mutate tasks in place; return the touched tasks.
+   */
+  async mutate(
+    kind: LedgerChange['kind'],
+    mutator: (ledger: TaskLedger) => TaskRecord[] | undefined,
+  ): Promise<{ ledger: TaskLedger; changed: readonly TaskRecord[] }> {
+    const run = async (): Promise<{ ledger: TaskLedger; changed: readonly TaskRecord[] }> => {
+      await this.load()
+      const draft: TaskLedger = structuredClone(this.ledger)
+      const changed = mutator(draft)
+      if (changed === undefined) {
+        return { ledger: this.ledger, changed: [] }
+      }
+      draft.revision += 1
+      const json = JSON.stringify(draft)
+      await persistAtomic(this.file, json)
+      this.ledger = draft
+      const change: LedgerChange = { revision: draft.revision, tasks: changed, kind }
+      for (const fn of this.subscribers) {
+        try {
+          fn(change)
+        } catch { /* subscriber errors never abort the write */ }
+      }
+      return { ledger: draft, changed }
+    }
+    const result = (this.queue = this.queue.then(run, run)) as ReturnType<typeof run>
+    return result
+  }
+
+  /** Persist the current ledger now (used after external reconciliation). */
+  async flush(kind: LedgerChange['kind'], changed: readonly TaskRecord[]): Promise<void> {
+    await this.mutate(kind, (ledger) => {
+      // replace tasks wholesale from the live snapshot objects
+      const byId = new Map(this.ledger.tasks.map(t => [t.id, t]))
+      ledger.tasks = ledger.tasks.map(t => byId.get(t.id) ?? t)
+      return [...changed]
+    })
+  }
+}
+
+/** Atomic file persist: write temp, then rename over the target. */
+async function persistAtomic(file: string, contents: string): Promise<void> {
+  await mkdir(dirname(file), { recursive: true })
+  const temp = join(dirname(file), `.${Math.random().toString(36).slice(2)}.tmp`)
+  await writeFile(temp, contents, 'utf8')
+  await rename(temp, file)
+}