dsh-taskboard 0.7.1 → 0.7.4

package/src/host/tools.ts

@@ -27,11 +27,13 @@ import { defineTool } from './sdk.ts'
 import {
   MAX_CHECKLIST_ITEMS,
   asIsolation,
+  asPermission,
   asStatus,
   asUrgency,
   canTransition,
   checklistFromTexts,
   defaultIsolationOf,
+  defaultPermissionOf,
   effectivePrompt,
   isClaim,
   isClaimedBy,
@@ -87,7 +89,7 @@ function taskDetail(t: TaskRecord & { effectivePrompt?: string }): string {
   const lines: string[] = [
     `任务 ${t.id} 「${t.title}」`,
     `状态: ${t.status} (v${t.version}) · 紧急度: ${t.urgency} · 项目: ${t.workspaceId}${t.blocked ? ' · 受阻' : ''}`,
-    `执行方式: ${t.execution.mode}${t.execution.cron !== undefined ? ` cron=${t.execution.cron}` : ''}`,
+    `执行方式: ${t.execution.mode}${t.execution.cron !== undefined ? ` 定期 cron=${t.execution.cron}` : ''}${t.execution.runAt !== undefined ? ` 定时(一次) runAt=${new Date(t.execution.runAt).toISOString()}` : ''}`,
     `隔离: ${t.isolation === 'none' ? '关闭（原目录执行）' : 'Git Worktree'}${t.branch !== undefined ? `（分支 ${t.branch}）` : ''}${t.branches !== undefined ? `（多仓库镜像 ${Object.keys(t.branches).length + (t.branch !== undefined ? 1 : 0)} 个仓库）` : ''}`,
   ]
   const holder = isClaimedBy(t)
@@ -377,7 +379,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     description:
       'Create a task on the board. Required: title, workspaceId (project), urgency (urgent/normal/relaxed). '
       + 'Optional: description, prompt (sent to a fresh session on execution), status (default todo), '
-      + 'execution mode (claim|scheduled + cron), model {provider, model} to pin executions to a model. '
+      + 'execution mode (claim | scheduled+cron 定期重复 | scheduled+runAt 定时一次), model {provider, model} to pin executions to a model. '
       + 'Do not track trivial requests as tasks.',
     parameters: {
       title: { type: 'string', required: true, description: 'Short imperative line (1..200 chars).' },
@@ -389,10 +391,11 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       execution: {
         type: 'object',
         additionalProperties: false,
-        description: 'Execution config: { mode: "claim" } (default) or { mode: "scheduled", cron: "m h dom mon dow" }.',
+        description: 'Execution config: { mode: "claim" } (default) | { mode: "scheduled", cron } periodic (定期, repeats) | { mode: "scheduled", runAt } one-shot (定时, fires once).',
         properties: {
           mode: { type: 'string', description: 'claim | scheduled.' },
-          cron: { type: 'string', description: 'Five-field cron expression (scheduled only).' },
+          cron: { type: 'string', description: 'Five-field cron expression (scheduled periodic only).' },
+          runAt: { type: 'string', description: 'One-shot trigger time: epoch ms or ISO string (scheduled one-shot only; must be in the future).' },
         },
       },
       model: {
@@ -409,6 +412,10 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         type: 'string',
         description: 'Code isolation for executions: "worktree" (each run gets a fresh git worktree on branch task/<标题>+<taskId>) or "none" (run in the project directory, zero git interaction). Omitted → the board default (看板设置 → 默认执行隔离; factory default "none").',
       },
+      permission: {
+        type: 'string',
+        description: 'Execution permission: "read-only", "workspace-write", or "danger-full-access". Omitted → the board default (看板设置 → 默认权限; factory default "workspace-write").',
+      },
       presetId: {
         type: 'string',
         description: 'Agent preset the execution session is composed from (its tool set / persona); default = the deployment default preset. Optional.',
@@ -434,9 +441,10 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       status?: string
       description?: string
       prompt?: string
-      execution?: { mode?: string; cron?: string }
+      execution?: { mode?: string; cron?: string; runAt?: string | number }
       model?: { provider?: string; model?: string }
       isolation?: string
+      permission?: string
       presetId?: string
       checklist?: string[]
     }, exec: unknown) {
@@ -457,6 +465,9 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
         // (看板设置) at creation, so later setting changes never rewrite
         // existing tasks.
         const isolation = args.isolation === undefined ? defaultIsolationOf(store.snapshot().settings) : asIsolation(args.isolation)
+        // Match the GUI create route: freeze the current board default onto
+        // the task so later settings changes do not silently alter a schedule.
+        const permission = args.permission === undefined ? defaultPermissionOf(store.snapshot().settings) : asPermission(args.permission)
         const presetId = args.presetId?.trim() || undefined
         // T9: match the GUI create route — trim and drop blank lines instead
         // of failing the whole call over one empty string.
@@ -475,6 +486,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           execution,
           model,
           isolation,
+          permission,
           ...(presetId !== undefined ? { presetId } : {}),
           ...(checklist !== undefined ? { checklist } : {}),
           version: 1,
@@ -498,7 +510,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
   disposers.push(register(defineTool({
     name: 'taskboard_update',
     description:
-      'Update a task\'s title/description/prompt/urgency/blocked. Requires ifVersion (read first). '
+      'Update a task\'s title/description/prompt/urgency/blocked/permission. Requires ifVersion (read first). '
       + 'The model and execution config are read-only through this tool (they belong to the task owner/user).',
     parameters: {
       id: { type: 'string', required: true, description: 'Task id.' },
@@ -508,6 +520,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       prompt: { type: 'string', description: 'New execution prompt.' },
       urgency: { type: 'string', description: 'urgent | normal | relaxed.' },
       blocked: { type: 'boolean', description: 'Blocked marker (work cannot continue right now).' },
+      permission: { type: 'string', description: 'Execution permission: read-only | workspace-write | danger-full-access.' },
     },
     output: {
       schema: JSON_OUT,
@@ -525,6 +538,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       prompt?: string
       urgency?: string
       blocked?: boolean
+      permission?: string
     }, exec: unknown) {
       try {
         const { actor } = caller(exec as ToolRunContext)
@@ -542,6 +556,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           if (args.prompt !== undefined) next.prompt = normalizePrompt(args.prompt)
           if (args.urgency !== undefined) next.urgency = asUrgency(args.urgency)
           if (args.blocked !== undefined) next.blocked = args.blocked
+          if (args.permission !== undefined) next.permission = asPermission(args.permission)
           next.version = task.version + 1
           next.updatedAt = deps.now()
           next.updatedBy = actor

package/src/index.ts

@@ -21,6 +21,7 @@ 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 { DEFAULT_MAX_CONCURRENT, ExecutionService, type EventsFace } from './host/execution.ts'
+import { scheduledSessionResumer, type ScheduledSessionDeps } from './host/scheduled-session.ts'
 import { createGitFace } from './host/git.ts'
 import { createRepoScanner } from './host/repos.ts'
 import { registerTaskboardRoutes } from './host/routes.ts'
@@ -183,6 +184,14 @@ export function apply(ctx: Context): void {
         store,
         agents: {
           create: (options): Promise<never> => agentCtx.agents.create(options as never) as Promise<never>,
+          resumeScheduled: scheduledSessionResumer({
+            agents: {
+              get: id => agentCtx.agents.get(id as never) as unknown as ReturnType<ScheduledSessionDeps['agents']['get']>,
+              resume: options => agentCtx.agents.resume(options as never) as Promise<never>,
+            },
+            persistence: () => agentCtx.get('sessionPersistence') as ReturnType<ScheduledSessionDeps['persistence']>,
+            isArchived: id => wsCtx.workspaceRegistry.archivedSessionIds.includes(id as never),
+          }),
         },
         workspaces: {
           get: id => workspaceFace(wsCtx.workspaceRegistry).get(id),

package/src/shared/api.ts

@@ -54,7 +54,7 @@ export type CreateTaskBody = {
   urgency: string
   description?: string
   prompt?: string
-  execution?: { mode?: string; cron?: string }
+  execution?: { mode?: string; cron?: string; runAt?: string | number }
   model?: TaskModel
   /** Code isolation for executions ('worktree' | 'none'); omitted = default. */
   isolation?: string
@@ -76,7 +76,7 @@ export type UpdateTaskBody = {
   blocked?: boolean
   /** Rebind the task to another project (GUI owner surface only). */
   workspaceId?: string
-  execution?: { mode?: string; cron?: string }
+  execution?: { mode?: string; cron?: string; runAt?: string | number }
   model?: TaskModel | null
   /** Change isolation; locked once the task has execution history. */
   isolation?: string
@@ -170,7 +170,7 @@ export type TaskTemplateSpec = {
   description?: string
   prompt?: string
   urgency?: string
-  execution?: { mode?: string; cron?: string }
+  execution?: { mode?: string; cron?: string; runAt?: string | number }
   model?: TaskModel
   isolation?: string
   presetId?: string

package/src/shared/protocol.ts

@@ -52,7 +52,7 @@ const TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>> = {
   todo: ['in_progress', 'backlog', 'canceled'],
   in_progress: ['in_review', 'todo', 'canceled'],
   in_review: ['in_progress', 'todo', 'done', 'canceled'],
-  done: ['archived'],
+  done: ['archived', 'todo'],
   canceled: ['archived', 'todo'],
   archived: [],
 }
@@ -220,8 +220,18 @@ export type ExecutionMode = 'claim' | 'scheduled'
  */
 export interface ExecutionConfig {
   mode: ExecutionMode
-  /** Five-field cron expression (minute hour day month weekday); required for `scheduled`. */
+  /**
+   * Five-field cron expression (minute hour day month weekday). Present on
+   * PERIODIC scheduled tasks (定期执行): the scheduler refires the task each
+   * time it comes due while the card sits in todo.
+   */
   cron?: string
+  /**
+   * One-shot trigger time (epoch ms). Present on ONE-SHOT scheduled tasks
+   * (定时执行): the scheduler fires the task once when due and consumes the
+   * field. Mutually exclusive with {@link cron}.
+   */
+  runAt?: number
   /** Next due time (epoch ms); maintained by the host scheduler. */
   nextRunAt?: number
   /** Last time the scheduler triggered this task (epoch ms). */
@@ -461,6 +471,8 @@ export type ExecutionRecord = {
   id: string
   /** The session this execution ran in; set once the session is really started. */
   sessionId?: string
+  /** Effective configuration of a scheduled session; used only for compatible reuse. */
+  sessionReuseKey?: string
   /** Trigger: manual button or the host scheduler. */
   trigger: 'manual' | 'scheduled'
   startedAt?: number
@@ -571,6 +583,13 @@ export type TaskRecord = {
   executions: ExecutionRecord[]
   /** How many older execution records were pruned by the retention cap. */
   executionsPruned?: number
+  /**
+   * Id of the task this card continues (0.7.x periodic execution): when a
+   * PERIODIC scheduled task succeeds, the finished card moves to in_review
+   * and a fresh todo card carrying the cron is minted to keep the cycle
+   * going. Absent on originally created tasks.
+   */
+  spawnedFrom?: string
   /** Soft-delete marker set by agent `taskboard_delete`; user confirms the purge. */
   trashedAt?: number
 }
@@ -591,6 +610,60 @@ export function pruneExecutions(task: TaskRecord): void {
   task.executionsPruned = (task.executionsPruned ?? 0) + dropped
 }
 
+/**
+ * Mint the successor card of a PERIODIC scheduled task that just succeeded
+ * (0.7.x): the finished card goes to in_review for acceptance while this
+ * fresh todo card carries the cron onward, keeping the cycle alive. The
+ * next run is recomputed from `now` (no compensating catch-up burst).
+ * Pure: the caller pushes the returned record into the ledger.
+ * @param source - the finished periodic task (still carrying its cron).
+ * @param prevExecutionId - id of the execution that just succeeded.
+ * @param now - current epoch ms.
+ * @returns the successor task record.
+ */
+export function spawnNextCycle(source: TaskRecord, prevExecutionId: string | undefined, now: number): TaskRecord {
+  const cron = source.execution.cron
+  if (cron === undefined) throw new Error('spawnNextCycle: source task has no cron')
+  const match = parseCron(cron)
+  const next = match === null ? undefined : nextCronTime(match, now) ?? undefined
+  if (next === undefined) throw new Error('spawnNextCycle: cron has no upcoming match within 4 years')
+  return {
+    id: newTaskId(),
+    title: source.title,
+    description: source.description,
+    prompt: source.prompt,
+    workspaceId: source.workspaceId,
+    urgency: source.urgency,
+    status: 'todo',
+    blocked: false,
+    execution: { mode: 'scheduled', cron, nextRunAt: next },
+    ...(source.model !== undefined ? { model: structuredClone(source.model) } : {}),
+    ...(source.isolation !== undefined ? { isolation: source.isolation } : {}),
+    ...(source.presetId !== undefined ? { presetId: source.presetId } : {}),
+    ...(source.permission !== undefined ? { permission: source.permission } : {}),
+    ...(source.checklist !== undefined
+      ? { checklist: source.checklist.map(item => ({ ...item, checked: false, checkedBy: undefined, checkedAt: undefined, note: undefined })) }
+      : {}),
+    ...(source.branch !== undefined ? { branch: source.branch } : {}),
+    ...(source.branches !== undefined ? { branches: { ...source.branches } } : {}),
+    spawnedFrom: source.id,
+    version: 1,
+    createdAt: now,
+    updatedAt: now,
+    createdBy: { kind: 'system' },
+    updatedBy: { kind: 'system' },
+    comments: [{
+      id: newCommentId(),
+      body: normalizeBody(`[系统] 定期任务上一轮执行完毕（执行 ${prevExecutionId ?? '未知'}），本卡承接定时继续下一轮；上一轮成果见 ${source.id} 的待验收。`),
+      systemKey: 'sys.spawnedFrom',
+      systemParams: { sourceId: source.id, executionId: prevExecutionId ?? '' },
+      version: 1,
+      createdAt: now,
+    }],
+    executions: [],
+  }
+}
+
 /** The whole durable ledger. */
 export type TaskLedger = {
   schemaVersion: number
@@ -710,24 +783,52 @@ export function asStatus(raw: string): TaskStatus {
   return raw as TaskStatus
 }
 
+/**
+ * Parse a raw runAt input: epoch ms number or ISO date string → epoch ms.
+ * @param raw - untyped runAt value.
+ * @returns the epoch ms, or undefined when absent.
+ */
+function normalizeRunAt(raw: unknown): number | undefined {
+  if (raw === undefined || raw === null) return undefined
+  if (typeof raw === 'number' && Number.isFinite(raw)) return Math.trunc(raw)
+  if (typeof raw === 'string') {
+    const t = Date.parse(raw)
+    if (Number.isNaN(t)) throw new Error('execution.runAt is not a valid time (epoch ms or ISO string)')
+    return t
+  }
+  throw new Error('execution.runAt must be an epoch ms number or an ISO date string')
+}
+
 /**
  * Validate an execution config request from raw tool/route input.
- * `scheduled` requires a valid cron; computes the first `nextRunAt` from
- * `now`.
+ * `scheduled` requires either a valid cron (periodic, 定期执行) or a runAt
+ * instant (one-shot, 定时执行); the two are mutually exclusive. A cron's
+ * first `nextRunAt` is computed from `now`.
  * @param raw - raw execution input ({@link ExecutionConfig} fields, untyped).
  * @param now - current epoch ms.
+ * @param opts - `allowPastRunAt` lets the import path keep a historical
+ *   one-shot instant instead of rejecting it.
  * @returns the normalized config.
  */
 export function normalizeExecution(
-  raw: { mode?: string; cron?: string },
+  raw: { mode?: string; cron?: string; runAt?: unknown },
   now: number,
+  opts?: { allowPastRunAt?: boolean },
 ): ExecutionConfig {
   const mode = raw.mode ?? 'claim'
   if (mode !== 'claim' && mode !== 'scheduled') {
     throw new Error("execution.mode must be 'claim' or 'scheduled'")
   }
   if (mode === 'claim') return { mode }
+  const runAt = normalizeRunAt(raw.runAt)
   const cron = (raw.cron ?? '').trim()
+  if (cron.length > 0 && runAt !== undefined) {
+    throw new Error('execution: cron and runAt are mutually exclusive (periodic vs one-shot)')
+  }
+  if (runAt !== undefined) {
+    if (!opts?.allowPastRunAt && runAt <= now) throw new Error('execution.runAt must be in the future')
+    return { mode, runAt, nextRunAt: runAt }
+  }
   const match = parseCron(cron)
   if (match === null) throw new Error('execution.cron is not a valid 5-field cron expression')
   const next = nextCronTime(match, now)
@@ -1053,8 +1154,9 @@ export function validateImportedTask(raw: unknown, now: number): { ok: true; tas
   if (!isValidTaskId(id)) return fail('missing/invalid id (must match ^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$)')
   try {
     const execution = normalizeExecution(
-      typeof e.execution === 'object' && e.execution !== null ? e.execution as { mode?: string; cron?: string } : {},
+      typeof e.execution === 'object' && e.execution !== null ? e.execution as { mode?: string; cron?: string; runAt?: unknown } : {},
       now,
+      { allowPastRunAt: true },
     )
     const comments: CommentRecord[] = []
     if (Array.isArray(e.comments)) {

package/src/shared/version.ts

@@ -6,5 +6,5 @@
  */
 
 /** The package version (must equal package.json "version"). */
-export const PLUGIN_VERSION = '0.7.1'
+export const PLUGIN_VERSION = '0.7.4'