dsh-taskboard 0.1.1 → 0.2.0

package/src/host/routes.ts

@@ -21,9 +21,12 @@ import {
   newTaskId,
   normalizeBody,
   normalizeExecution,
+  normalizeModel,
   normalizePrompt,
   normalizeTitle,
   summarize,
+  syncClaim,
+  type TaskModel,
   type TaskRecord,
 } from '../shared/protocol.ts'
 import { ROUTE_PREFIX, SSE_PATH, type ApiFail, type ApiResult } from '../shared/api.ts'
@@ -43,6 +46,23 @@ export interface TaskboardRoutesOptions {
   now: () => number
   /** Manual-run hook (the execution service); absent → 501. */
   run?: (taskId: string) => Promise<{ ok: true; executionId: string; sessionId: string } | { ok: false; error: string }>
+  /** Cancel hook (the execution service); absent → 501. */
+  cancel?: (taskId: string) => Promise<{ ok: true; executionId: string } | { ok: false; error: string }>
+  /**
+   * Registered model provider routes (from the host llm runtime), for
+   * advisory validation of pinned models; undefined = runtime unavailable.
+   */
+  modelProviders?: () => string[] | undefined
+}
+
+/** Validate a pinned model: structural check always, provider route when known. */
+function checkModel(raw: unknown, modelProviders?: () => string[] | undefined): TaskModel {
+  const model = normalizeModel(raw)
+  const providers = modelProviders?.()
+  if (providers !== undefined && !providers.includes(model.provider)) {
+    throw new Error(`Error: invalid_input: model provider "${model.provider}" has no registered route (available: ${providers.join(', ')})`)
+  }
+  return model
 }
 
 /** JSON-envelope writer. */
@@ -117,14 +137,6 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
   }
   store.subscribe(broadcast)
 
-  const taskPath = (id: string, action?: string): RegExp | null => {
-    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-    const pattern = action === undefined
-      ? `^${ROUTE_PREFIX}/tasks/${escaped}$`
-      : `^${ROUTE_PREFIX}/tasks/${escaped}/${action}$`
-    return new RegExp(pattern)
-  }
-
   const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     try {
       const url = new URL(req.url ?? '/', 'http://x')
@@ -181,7 +193,7 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
           const urgency = asUrgency(str(body, 'urgency') ?? '')
           const status = str(body, 'status') === null ? 'todo' as const : asStatus(str(body, 'status')!)
           const execution = normalizeExecution((body.execution as { mode?: string; cron?: string } | undefined) ?? {}, options.now())
-          const model = body.model as { provider: string; model: string } | undefined
+          const model = body.model === undefined ? undefined : checkModel(body.model, options.modelProviders)
           const now = options.now()
           const task: TaskRecord = {
             id: newTaskId(),
@@ -245,7 +257,7 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             // The GUI (task owner surface) may edit model/execution; null clears the model.
             if (body.execution !== undefined) next.execution = normalizeExecution(body.execution as { mode?: string; cron?: string }, options.now())
             if (body.model === null) next.model = undefined
-            else if (body.model !== undefined) next.model = body.model as { provider: string; model: string }
+            else if (body.model !== undefined) next.model = checkModel(body.model, options.modelProviders)
             next.version = task.version + 1
             next.updatedAt = options.now()
             next.updatedBy = { kind: 'user' }
@@ -270,6 +282,8 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             next.updatedAt = options.now()
             next.updatedBy = { kind: 'user' }
             if (task.status === 'todo' && to === 'in_progress') next.blocked = false
+            // A user move records no holder; leaving in_progress releases any hold.
+            syncClaim(next, to, options.now())
             await store.mutate('task-moved', ledger => {
               const i = ledger.tasks.findIndex(t => t.id === id)
               ledger.tasks[i] = next
@@ -332,6 +346,20 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
             }
             return
           }
+          if (action === 'cancel') {
+            if (options.cancel === undefined) {
+              const f = fail('invalid_input', 'execution service unavailable')
+              json(res, f.res, 501)
+              return
+            }
+            const result = await options.cancel(id)
+            if (result.ok) json(res, { ok: true, value: { cancelled: true, executionId: result.executionId } }, 202)
+            else {
+              const f = fail('invalid_input', result.error)
+              json(res, f.res, f.status)
+            }
+            return
+          }
           const f = fail('not_found', `unknown action ${action}`)
           json(res, f.res, f.status)
         } catch (error) {
@@ -341,7 +369,6 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
         return
       }
 
-      void taskPath
       res.writeHead(404)
       res.end()
     } catch (error) {

package/src/host/scheduler.ts

@@ -9,7 +9,7 @@
  * @module dsh-taskboard/host/scheduler
  */
 import { nextCronTime, parseCron, type TaskLedger } from '../shared/protocol.ts'
-import type { ExecutionService } from './execution.ts'
+import { DEFAULT_MAX_CONCURRENT, type ExecutionService } from './execution.ts'
 import type { TaskStore } from './store.ts'
 
 /** Tick cadence. */
@@ -21,8 +21,10 @@ const SKIP_AFTER_MS = 5 * 60_000
 /** Everything the scheduler needs. */
 export interface SchedulerDeps {
   store: TaskStore
-  execution: Pick<ExecutionService, 'run'>
+  execution: Pick<ExecutionService, 'run' | 'inFlight'>
   now: () => number
+  /** Max concurrently running executions (default 3; must match the execution service). */
+  maxConcurrent?: number
   /** Timer face (injectable for tests). */
   timers?: {
     setInterval(fn: () => void, ms: number): unknown
@@ -35,6 +37,7 @@ export interface SchedulerDeps {
  */
 export class SchedulerService {
   private handle: unknown
+  private catchup: ReturnType<typeof setTimeout> | undefined
 
   /** @param deps - store + execution + clock. */
   constructor(private readonly deps: SchedulerDeps) {}
@@ -46,12 +49,17 @@ export class SchedulerService {
       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)
+    // Catch up promptly on host restart: run one tick soon after start. The
+    // handle is cleared on dispose so a torn-down scheduler never fires.
+    this.catchup = setTimeout(() => { void this.tick() }, 3_000)
   }
 
   /** Stop ticking. */
   dispose(): void {
+    if (this.catchup !== undefined) {
+      clearTimeout(this.catchup)
+      this.catchup = undefined
+    }
     if (this.handle === undefined) return
     const timers = this.deps.timers ?? { clearInterval: (h: unknown) => clearInterval(h as ReturnType<typeof setInterval>) }
     timers.clearInterval(this.handle)
@@ -60,13 +68,21 @@ export class SchedulerService {
 
   /** One scheduler pass (exported for tests). */
   async tick(): Promise<void> {
+    // Load once before reading: snapshot() does not trigger a load, and the
+    // scheduler may be the first consumer after a host restart (otherwise it
+    // would tick over an empty ledger until something else loads it).
+    await this.deps.store.load()
     const now = this.deps.now()
     const ledger: TaskLedger = this.deps.store.snapshot()
+    const atCapacity = this.deps.execution.inFlight() >= (this.deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT)
     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
+      // At the concurrency cap: leave nextRunAt in the past and retry next
+      // tick — advancing here would silently burn this window.
+      if (atCapacity) continue
       const missed = now - task.execution.nextRunAt > SKIP_AFTER_MS
 
       // Advance the schedule FIRST (idempotent under re-ticks), then run

package/src/host/store.ts

@@ -11,6 +11,7 @@ import { dirname, join } from 'node:path'
 import {
   LEDGER_SCHEMA_VERSION,
   emptyLedger,
+  pruneExecutions,
   type TaskLedger,
   type TaskRecord,
 } from '../shared/protocol.ts'
@@ -55,7 +56,18 @@ export class TaskStore {
       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 }
+        const tasks = parsed.tasks as TaskRecord[]
+        // Migration from pre-claim-field ledgers: an agent-held in_progress
+        // task carried its holder in updatedBy — backfill the explicit claim
+        // fields so the hold survives user edits (updatedBy is audit-only).
+        for (const task of tasks) {
+          if (task.status === 'in_progress' && task.claimedBy === undefined
+            && task.updatedBy?.kind === 'agent' && typeof task.updatedBy.sessionId === 'string') {
+            task.claimedBy = task.updatedBy.sessionId
+            task.claimedAt = task.updatedAt
+          }
+        }
+        this.ledger = { schemaVersion: LEDGER_SCHEMA_VERSION, revision: parsed.revision, tasks }
       }
     } catch (error) {
       const code = (error as NodeJS.ErrnoException).code
@@ -70,14 +82,19 @@ export class TaskStore {
     this.loaded = true
   }
 
-  /** The current immutable snapshot. */
+  /**
+   * The current snapshot — a deep-frozen clone. Mutating the returned value
+   * throws (strict mode) instead of silently bypassing the revision/persist
+   * path; internal state is never handed out.
+   */
   snapshot(): TaskLedger {
-    return this.ledger
+    return deepFreeze(structuredClone(this.ledger))
   }
 
-  /** Find a task by id. */
+  /** Find a task by id (frozen clone; internal state is never handed out). */
   get(id: string): TaskRecord | undefined {
-    return this.ledger.tasks.find(t => t.id === id)
+    const task = this.ledger.tasks.find(t => t.id === id)
+    return task === undefined ? undefined : deepFreeze(structuredClone(task))
   }
 
   /** Subscribe to committed changes; returns the unsubscribe. */
@@ -103,6 +120,9 @@ export class TaskStore {
       if (changed === undefined) {
         return { ledger: this.ledger, changed: [] }
       }
+      // Retention cap: every committed mutation re-checks the touched tasks,
+      // so execution history can never grow unbounded (SSE state payload).
+      for (const task of changed) pruneExecutions(task)
       draft.revision += 1
       const json = JSON.stringify(draft)
       await persistAtomic(this.file, json)
@@ -118,16 +138,17 @@ export class TaskStore {
     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]
-    })
+/** Recursively freeze a plain-data value (defense in depth for handed-out snapshots). */
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === 'object') {
+    if (!Object.isFrozen(value)) Object.freeze(value)
+    for (const key of Object.keys(value as Record<string, unknown>)) {
+      deepFreeze((value as Record<string, unknown>)[key])
+    }
   }
+  return value
 }
 
 /** Atomic file persist: write temp, then rename over the target. */

package/src/host/tools.ts

@@ -26,13 +26,16 @@ import {
   canTransition,
   effectivePrompt,
   isClaim,
+  isClaimedBy,
   newCommentId,
   newTaskId,
   normalizeBody,
   normalizeExecution,
+  normalizeModel,
   normalizePrompt,
   normalizeTitle,
   summarize,
+  syncClaim,
   type Actor,
   type TaskModel,
   type TaskRecord,
@@ -72,6 +75,8 @@ function taskDetail(t: TaskRecord & { effectivePrompt?: string }): string {
     `状态: ${t.status} (v${t.version}) · 紧急度: ${t.urgency} · 项目: ${t.workspaceId}${t.blocked ? ' · 受阻' : ''}`,
     `执行方式: ${t.execution.mode}${t.execution.cron !== undefined ? ` cron=${t.execution.cron}` : ''}`,
   ]
+  const holder = isClaimedBy(t)
+  if (holder !== undefined) lines.push(`认领: agent ${String(holder).slice(0, 24)}（持有期间其他会话不可移动）`)
   if (t.execution.nextRunAt !== undefined) lines.push(`下次触发: ${new Date(t.execution.nextRunAt).toISOString()}`)
   if (t.model !== undefined) lines.push(`固定模型: ${t.model.provider}/${t.model.model}`)
   lines.push(`描述: ${t.description.length > 0 ? t.description : '（无）'}`)
@@ -151,6 +156,22 @@ export interface ToolDeps {
   workspaces: WorkspaceFace
   /** Current epoch ms (injectable for tests). */
   now: () => number
+  /**
+   * Registered model provider routes (from the host llm runtime), for
+   * advisory validation of pinned models; undefined = runtime unavailable,
+   * in which case only the structural check applies.
+   */
+  modelProviders?: () => string[] | undefined
+}
+
+/** Validate a pinned model: structural check always, provider route when known. */
+function checkModel(deps: ToolDeps, raw: unknown): TaskModel {
+  const model = normalizeModel(raw)
+  const providers = deps.modelProviders?.()
+  if (providers !== undefined && !providers.includes(model.provider)) {
+    throw new ToolError(ERR.invalidInput, `model provider "${model.provider}" has no registered route (available: ${providers.join(', ')})`)
+  }
+  return model
 }
 
 /** Resolve the calling agent's actor and session id. */
@@ -358,9 +379,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           throw new ToolError(ERR.invalidTransition, 'a new task cannot start as done/archived')
         }
         const execution = normalizeExecution(args.execution ?? {}, deps.now())
-        if (args.model !== undefined && (typeof args.model.provider !== 'string' || typeof args.model.model !== 'string')) {
-          throw new ToolError(ERR.invalidInput, 'model must be { provider: string, model: string }')
-        }
+        const model = args.model !== undefined ? checkModel(deps, args.model) : undefined
         const now = deps.now()
         const task: TaskRecord = {
           id: newTaskId(),
@@ -372,7 +391,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           status,
           blocked: false,
           execution,
-          model: args.model as TaskModel | undefined,
+          model,
           version: 1,
           createdAt: now,
           updatedAt: now,
@@ -483,10 +502,11 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         if (!canTransition(task.status, to)) {
           throw new ToolError(ERR.invalidTransition, `illegal transition ${task.status} → ${to}`)
         }
-        // Exclusive hold: while a task is in_progress under an agent, no other
-        // session may move it at all (that would be a takeover).
-        if (task.status === 'in_progress' && task.updatedBy.kind === 'agent' && task.updatedBy.sessionId !== actor.sessionId) {
-          throw new ToolError(ERR.forbidden, `task is held by session ${task.updatedBy.sessionId}; never take over another session's claim`)
+        // Exclusive hold: while a task is in_progress under a session
+        // (explicit claimedBy — an agent claim or a live execution), no other
+        // session may move it (that would be a takeover).
+        if (task.status === 'in_progress' && task.claimedBy !== undefined && task.claimedBy !== actor.sessionId) {
+          throw new ToolError(ERR.forbidden, `task is held by session ${task.claimedBy}; never take over another session's claim`)
         }
         // Claim boundary: the calling session must belong to the task's project.
         if (isClaim(task.status, to)) {
@@ -501,6 +521,8 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         next.updatedAt = deps.now()
         next.updatedBy = actor
         if (isClaim(task.status, to)) next.blocked = false
+        // Record the holder on a claim; every move out of in_progress releases it.
+        syncClaim(next, to, deps.now(), isClaim(task.status, to) ? actor.sessionId : undefined)
         await store.mutate('task-moved', ledger => {
           const i = ledger.tasks.findIndex(t => t.id === args.id)
           ledger.tasks[i] = next

package/src/index.ts

@@ -20,7 +20,7 @@ import type {} from '@deepseek-ai/dsh-tools'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-agent'
 import { PROTOCOL_SECTION_NAME, PROTOCOL_SECTION_ORDER, TASKBOARD_PROTOCOL } from './host/protocol-text.ts'
-import { ExecutionService, type EventsFace } from './host/execution.ts'
+import { DEFAULT_MAX_CONCURRENT, ExecutionService, type EventsFace } from './host/execution.ts'
 import { registerTaskboardRoutes } from './host/routes.ts'
 import { SchedulerService } from './host/scheduler.ts'
 import { dshHomePath } from './host/sdk.ts'
@@ -43,6 +43,8 @@ export const inject = ['tools', 'systemPrompt']
 export function apply(ctx: Context): void {
   const store = new TaskStore({ file: dshHomePath(LEDGER_FILE) })
   const now = () => Date.now()
+  // Global execution concurrency cap (DSH_TASKBOARD_MAX_CONCURRENT overrides).
+  const maxConcurrent = Math.max(1, Number.parseInt(process.env.DSH_TASKBOARD_MAX_CONCURRENT ?? '', 10) || DEFAULT_MAX_CONCURRENT)
 
   // Agent workflow protocol (claim discipline, retry rules, done-gate).
   const disposeSection = ctx.systemPrompt.section({
@@ -56,10 +58,24 @@ export function apply(ctx: Context): void {
   // workspace registry (claim boundary + project execution need it).
   ctx.inject(['workspaceRegistry'], (wsCtx: Context) => {
     const disposers: Array<() => void> = []
+
+    // Registered model provider routes (from the host llm runtime), read
+    // lazily at call time so late availability still applies; undefined when
+    // the runtime is absent → only structural model validation runs.
+    const modelProviders = (): string[] | undefined => {
+      try {
+        const llm = wsCtx.get('llm') as { listProviders?: () => Array<{ id: string }> } | undefined
+        return llm === undefined || typeof llm.listProviders !== 'function'
+          ? undefined
+          : llm.listProviders().map(p => p.id)
+      } catch { return undefined }
+    }
+
     disposers.push(...registerTaskboardTools(wsCtx, {
       store,
       workspaces: workspaceFace(wsCtx.workspaceRegistry),
       now,
+      modelProviders,
     }))
 
     // Settlement listener over the session event bus.
@@ -84,6 +100,16 @@ export function apply(ctx: Context): void {
         },
         events,
         now,
+        renameSession: (sessionId, title) => {
+          // Best-effort: pin the execution session's title to the task title
+          // through the log-backed session-title service (user-sourced rename).
+          try {
+            const sessions = agentCtx.get('sessions') as { get(id: string): unknown } | undefined
+            const sessionTitle = agentCtx.get('sessionTitle') as { rename(session: unknown, title: string): unknown } | undefined
+            const session = sessions?.get(sessionId)
+            if (session !== undefined && sessionTitle !== undefined) sessionTitle.rename(session, title)
+          } catch { /* cosmetic */ }
+        },
         defaultModel: () => {
           try {
             const selection = agentCtx.get('agentDefaultModel') as { currentSelection?: () => { provider: string; model: string } | undefined } | undefined
@@ -91,6 +117,7 @@ export function apply(ctx: Context): void {
             return read === undefined ? undefined : read.call(selection)
           } catch { return undefined }
         },
+        maxConcurrent,
       })
 
       // /dsh-taskboard routes (the run action reaches the execution service).
@@ -101,13 +128,20 @@ export function apply(ctx: Context): void {
           workspaces: workspaceFace(wsCtx.workspaceRegistry),
           now,
           run: (taskId: string) => execution.run(taskId, 'manual'),
+          cancel: (taskId: string) => execution.cancel(taskId),
+          modelProviders,
         })
         return () => disposeRoutes?.()
       })
 
+      // Startup reconciliation: executions left 'running' by a previous host
+      // process are marked failed and their tasks handed back to todo (their
+      // settlement watchers died with that process).
+      void execution.reconcile()
+
       // Host-side cron scheduler: due scheduled tasks execute even with no
-      // browser open.
-      const scheduler = new SchedulerService({ store, execution, now })
+      // browser open. Shares the execution concurrency cap.
+      const scheduler = new SchedulerService({ store, execution, now, maxConcurrent })
       scheduler.start()
       disposers.push(() => scheduler.dispose())
 

package/src/shared/protocol.ts

@@ -271,6 +271,15 @@ export type TaskRecord = {
   blocked: boolean
   execution: ExecutionConfig
   model?: TaskModel
+  /**
+   * The session currently holding the in-progress claim (explicit claim or a
+   * live execution). Present only while `status === 'in_progress'`: any move
+   * out of in_progress releases it. `updatedBy` is audit-only — user edits no
+   * longer erase the holder.
+   */
+  claimedBy?: string
+  /** When the current holder claimed the task (epoch ms). */
+  claimedAt?: number
   version: number
   createdAt: number
   updatedAt: number
@@ -278,10 +287,28 @@ export type TaskRecord = {
   updatedBy: Actor
   comments: CommentRecord[]
   executions: ExecutionRecord[]
+  /** How many older execution records were pruned by the retention cap. */
+  executionsPruned?: number
   /** Soft-delete marker set by agent `taskboard_delete`; user confirms the purge. */
   trashedAt?: number
 }
 
+/** Retention cap: how many execution records each task keeps (oldest pruned). */
+export const MAX_EXECUTIONS = 20
+
+/**
+ * Enforce the execution-record retention cap on one task (in place): keep the
+ * newest {@link MAX_EXECUTIONS} records, count the dropped ones in
+ * `executionsPruned`. Running records are always the newest, never dropped.
+ * @param task - the task to prune.
+ */
+export function pruneExecutions(task: TaskRecord): void {
+  if (task.executions.length <= MAX_EXECUTIONS) return
+  const dropped = task.executions.length - MAX_EXECUTIONS
+  task.executions = task.executions.slice(-MAX_EXECUTIONS)
+  task.executionsPruned = (task.executionsPruned ?? 0) + dropped
+}
+
 /** The whole durable ledger. */
 export type TaskLedger = {
   schemaVersion: number
@@ -424,9 +451,51 @@ export function effectivePrompt(task: TaskRecord): string {
  * @param task - the task.
  */
 export function isClaimedBy(task: TaskRecord): string | undefined {
-  return task.status === 'in_progress' && task.updatedBy.kind === 'agent'
-    ? task.updatedBy.sessionId
-    : undefined
+  return task.status === 'in_progress' && task.claimedBy !== undefined ? task.claimedBy : undefined
+}
+
+/**
+ * Maintain the explicit claim fields around a status change: entering
+ * in_progress under a session records the holder (an execution-start or an
+ * agent claim); every move out of in_progress releases the claim (handoff,
+ * give-back, cancel). A user-driven move into in_progress records no holder —
+ * no session works on it yet.
+ * @param task - the task being written (mutated in place).
+ * @param to - the target status.
+ * @param now - current epoch ms.
+ * @param holder - the session id claiming the task, when applicable.
+ */
+export function syncClaim(task: TaskRecord, to: TaskStatus, now: number, holder?: string): void {
+  if (to !== 'in_progress') {
+    delete task.claimedBy
+    delete task.claimedAt
+  } else if (holder !== undefined) {
+    task.claimedBy = holder
+    task.claimedAt = now
+  }
+}
+
+/**
+ * Validate and normalize a pinned model: `{ provider, model }`, both
+ * non-empty trimmed strings.
+ * @param raw - the raw input.
+ * @returns the normalized model.
+ * @throws when the shape or the fields are invalid.
+ */
+export function normalizeModel(raw: unknown): TaskModel {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new Error('model must be { provider: string, model: string }')
+  }
+  const { provider, model } = raw as { provider?: unknown; model?: unknown }
+  if (typeof provider !== 'string' || typeof model !== 'string') {
+    throw new Error('model must be { provider: string, model: string }')
+  }
+  const p = provider.trim()
+  const m = model.trim()
+  if (p.length === 0 || m.length === 0) {
+    throw new Error('model.provider and model.model must be non-empty strings')
+  }
+  return { provider: p, model: m }
 }
 
 /**

package/src/shared/version.ts

@@ -0,0 +1,9 @@
+/**
+ * The plugin package version shown in the board UI. Kept in sync with
+ * package.json by a regression test (tests lock drift).
+ *
+ * @module dsh-taskboard/shared/version
+ */
+
+/** The package version (must equal package.json "version"). */
+export const PLUGIN_VERSION = '0.2.0'