@linxin666/dsh-client-ui-task-board 0.4.1 → 0.4.3

package/src/core/tasks.ts

@@ -10,6 +10,9 @@ import type { TaskHandover, TaskHandoverInput } from './handover.ts'
 /** Task lifecycle status, one per kanban column. */
 export type TaskStatus = 'backlog' | 'todo' | 'running' | 'done' | 'failed'
 
+/** Settled outcome of one execution attempt. */
+export type ExecutionOutcome = 'succeeded' | 'failed' | 'cancelled'
+
 /**
  * One real execution attempt: the run's own id, the dsh session that ran it
  * (filled once the session is created), and the settled outcome once the
@@ -25,7 +28,7 @@ export interface ExecutionRecord {
   /** When the run settled; absent while still running. */
   endedAt: number | undefined
   /** Outcome once settled. */
-  result: 'succeeded' | 'failed' | 'cancelled' | undefined
+  result: ExecutionOutcome | undefined
   /** Human failure text when the run failed (prompt rejection or agent error). */
   error: string | undefined
   /**
@@ -38,6 +41,20 @@ export interface ExecutionRecord {
   frozenAt?: number
   /** Freeze source session captured from the card snapshot when the run opened. */
   frozenBy?: string
+  /**
+   * Cascade run group shared by the parent execution and every descendant
+   * execution one run request opened. Absent on a plain single-task run.
+   */
+  runGroupId?: string
+  /**
+   * A cascade parent's own session outcome, recorded as soon as its own turn
+   * settles and held while its subtask executions finish. The execution stays
+   * open (no `endedAt`) until the last child settles; the Host monitor skips
+   * an execution whose own outcome is already recorded.
+   */
+  ownResult?: ExecutionOutcome
+  /** Human failure text that arrived with {@link ownResult}. */
+  ownError?: string
 }
 
 /**
@@ -203,6 +220,14 @@ export interface TaskRecord {
   description: string
   /** The prompt sent to dsh when this task is executed. */
   prompt: string
+  /**
+   * Parent task id: present only on a subtask. The Host owns the lineage gate
+   * (see `core/subtask.ts`), which refuses a cycle, an archived parent, and
+   * any link that would exceed `maxSubtaskDepth` — so every chain the Host
+   * wrote under the current setting is at most that many links long. Lowering
+   * the limit later neither rewrites nor deletes an already stored link.
+   */
+  parentId?: string
   /** Current column. */
   status: TaskStatus
   /** Creation instant (ms epoch). */
@@ -244,6 +269,15 @@ export interface TaskRecord {
    * {@link reusableSessionId}).
    */
   reuseSession?: boolean
+  /**
+   * Run this task's subtree as an Agent Team instead of one Host-launched
+   * session per participant: the root becomes the Team Lead session and the
+   * Host spawns one teammate for each direct subtask inside it. Absent or false
+   * keeps the plain concurrent cascade. A deployment that does not serve the
+   * Agent Teams service refuses a team run instead of silently falling back,
+   * and a subtask's own permission pin cannot be honored in this mode.
+   */
+  teamRun?: boolean
   /**
    * Frozen context snapshot for a continuation card; absent on plain tasks.
    * Sanitized before it enters the ledger (redaction, slash-command taint,
@@ -302,6 +336,12 @@ export interface NewTaskInput {
   title: string
   description: string
   prompt: string
+  /**
+   * Parent task id, turning this creation into a subtask. Absent keeps a root
+   * task; the create use case validates the link (existence, depth) and
+   * inherits the parent's unset execution targets.
+   */
+  parentId?: string
   /** Workspace the execution must run in; empty/absent = the recent workspace. */
   workspaceId?: string
   /** Agent preset the execution session must be composed from; empty/absent = deployment default. */
@@ -312,6 +352,8 @@ export interface NewTaskInput {
   model?: string
   /** Reuse the previous execution's session for later runs (issue #1419). */
   reuseSession?: boolean
+  /** Run the subtree as an Agent Team (Team Lead session plus one teammate per direct subtask). */
+  teamRun?: boolean
   /**
    * Optional scheduled-run rule requested at creation time (the new-task
    * dialog): an enable flag plus a 5-field cron expression. The create use
@@ -397,6 +439,7 @@ export function createTask(input: NewTaskInput, now: number, id: string): TaskRe
     title: input.title.trim(),
     description: input.description.trim(),
     prompt: input.prompt.trim(),
+    parentId: normalizeTargetId(input.parentId),
     status: 'todo',
     createdAt: now,
     updatedAt: now,
@@ -406,6 +449,7 @@ export function createTask(input: NewTaskInput, now: number, id: string): TaskRe
     permission: isTaskPermission(input.permission) ? input.permission : undefined,
     model: normalizeTargetId(input.model),
     reuseSession: input.reuseSession === true ? true : undefined,
+  teamRun: input.teamRun === true ? true : undefined,
     ...(input.freeze === undefined ? {} : { freeze: freezeOf(input.freeze, now) }),
     ...(input.handover === undefined ? {} : { handover: { ...input.handover, bundledAt: now } }),
     ...(tags === undefined ? {} : { tags }),
@@ -445,12 +489,15 @@ export function withSchedule(
 /**
  * Open a fresh execution on a task: move it to 'running' and append a
  * running execution record. Returns the new task and the new execution.
+ * @param runGroupId - cascade run group, when this run also opened executions
+ *   for the task's subtasks (see `core/subtask.ts`).
  */
 export function startExecution(
   task: TaskRecord,
   now: number,
   executionId: string,
   initiatedBy?: string,
+  runGroupId?: string,
 ): { task: TaskRecord; execution: ExecutionRecord } {
   const execution: ExecutionRecord = {
     id: executionId,
@@ -459,6 +506,7 @@ export function startExecution(
     endedAt: undefined,
     result: undefined,
     error: undefined,
+    ...(runGroupId === undefined || runGroupId === '' ? {} : { runGroupId }),
     ...(initiatedBy === undefined || initiatedBy === '' ? {} : { initiatedBy }),
     // Capture the card's freeze provenance on the execution record so the
     // audit trail stays queryable even if the snapshot is replaced later.
@@ -486,7 +534,7 @@ export function startExecution(
 export function settleExecution(
   task: TaskRecord,
   executionId: string,
-  outcome: 'succeeded' | 'failed' | 'cancelled',
+  outcome: ExecutionOutcome,
   now: number,
   error: string | undefined,
 ): TaskRecord {

package/src/core/use-cases/task-archive.ts

@@ -1,9 +1,16 @@
 /**
  * Archive/restore task use case: move a task off the main board and back,
- * whatever its status but `running`. The task keeps its status, execution history, and
- * transcript references, while archiving disarms any schedule so it cannot
- * create more execution records until the user restores and re-enables it.
+ * whatever its status but running. The task keeps its status, execution
+ * history, and transcript references, while archiving disarms any schedule so
+ * it cannot create more execution records until the user restores and
+ * re-enables it.
+ *
+ * Subtask trees move as a unit: archiving takes the whole subtree (an on-board
+ * subtask under an archived parent would be unreachable from its parent) and
+ * refuses the whole group while any member is running. Restoring brings the
+ * task, its ancestors and its subtree back together.
  */
+import { DEFAULT_SUBTASK_DEPTH, ancestorChain, descendantTasks, normalizeSubtaskDepth } from '../subtask.ts'
 import type { TaskRecord } from '../tasks.ts'
 import { ARCHIVABLE_STATUSES } from '../tasks.ts'
 
@@ -15,21 +22,37 @@ export interface ArchiveTaskResult {
   archived: boolean
 }
 
+/** The archive/restore id set: the task, its subtree, and (for restore) its ancestors. */
+function groupIds(tasks: readonly TaskRecord[], id: string, maxSubtaskDepth: number, withAncestors: boolean): Set<string> {
+  const target = tasks.find(task => task.id === id)
+  const ids = new Set<string>([id])
+  for (const task of descendantTasks(tasks, id, normalizeSubtaskDepth(maxSubtaskDepth))) ids.add(task.id)
+  if (withAncestors && target !== undefined) {
+    for (const ancestor of ancestorChain(tasks, target)) ids.add(ancestor.id)
+  }
+  return ids
+}
+
 /**
- * Archive one task: only a `running` task stays on the board (its runner
- * still owns its lifecycle until the execution settles); every other status
- * can be archived. Archiving disarms a schedule; already-archived tasks are
- * a no-op.
+ * Archive one task and its subtasks: only a running member keeps the group on
+ * the board (its runner still owns its lifecycle until the execution settles);
+ * any other status can be archived. Archiving disarms schedules; an
+ * already-archived task is a no-op.
  */
 export function applyArchiveTask(
   tasks: readonly TaskRecord[],
   id: string,
   now: number,
+  maxSubtaskDepth: number = DEFAULT_SUBTASK_DEPTH,
 ): ArchiveTaskResult {
+  const target = tasks.find(task => task.id === id)
+  if (target === undefined || target.archivedAt !== undefined) return { tasks, archived: false }
+  const ids = groupIds(tasks, id, maxSubtaskDepth, false)
+  const declining = tasks.some(task => ids.has(task.id) && !(ARCHIVABLE_STATUSES as readonly string[]).includes(task.status))
+  if (declining) return { tasks, archived: false }
   let applied = false
   const next = tasks.map(task => {
-    if (task.id !== id || task.archivedAt !== undefined) return task
-    if (!(ARCHIVABLE_STATUSES as readonly string[]).includes(task.status)) return task
+    if (!ids.has(task.id) || task.archivedAt !== undefined) return task
     applied = true
     const schedule = task.schedule === undefined
       ? undefined
@@ -44,11 +67,22 @@ export function applyArchiveTask(
   return { tasks: next, archived: applied }
 }
 
-/** Restore one task back onto the main board (clears the archive marker). */
-export function applyRestoreTask(tasks: readonly TaskRecord[], id: string, now: number): ArchiveTaskResult {
+/**
+ * Restore one task back onto the main board, together with its ancestors (an
+ * on-board subtask must not point at an archived parent) and its subtasks.
+ */
+export function applyRestoreTask(
+  tasks: readonly TaskRecord[],
+  id: string,
+  now: number,
+  maxSubtaskDepth: number = DEFAULT_SUBTASK_DEPTH,
+): ArchiveTaskResult {
+  const target = tasks.find(task => task.id === id)
+  if (target === undefined || target.archivedAt === undefined) return { tasks, archived: false }
+  const ids = groupIds(tasks, id, maxSubtaskDepth, true)
   let applied = false
   const next = tasks.map(task => {
-    if (task.id !== id || task.archivedAt === undefined) return task
+    if (!ids.has(task.id) || task.archivedAt === undefined) return task
     applied = true
     const { archivedAt: _archived, ...rest } = task
     return { ...rest, updatedAt: now }

package/src/core/use-cases/task-create.ts

@@ -1,35 +1,70 @@
 /**
  * Create-task use case: mint a new task from user input, rejecting a blank
- * title. Pure ledger transition (no persistence or notify — the controller
- * orchestrates those), so it is unit-testable without any runtime face.
+ * title and any parent link the lineage gate refuses. Pure ledger transition
+ * (no persistence or notify - the controller orchestrates those), so it is
+ * unit-testable without any runtime face.
  */
 import { isValidCron, nextRunAtMs } from '../schedule.ts'
+import { DEFAULT_SUBTASK_DEPTH, normalizeSubtaskDepth, taskDepth } from '../subtask.ts'
 import { createTask, withSchedule, type NewTaskInput, type TaskRecord } from '../tasks.ts'
 
 /** Result of a create transition: the new task (when accepted) + the next ledger. */
 export interface CreateTaskResult {
-  /** The minted task, or undefined when the input was rejected (blank title). */
+  /** The minted task, or undefined when the input was rejected. */
   task: TaskRecord | undefined
   /** The next ledger; identical reference when rejected. */
   tasks: readonly TaskRecord[]
+  /** Why the input was rejected; absent when a task was minted. */
+  error?: string
 }
 
 /**
  * Apply a create against the current ledger. Returns the new task and the
- * appended ledger, or the unchanged ledger when the title is blank.
+ * appended ledger, or the unchanged ledger when the title is blank or the
+ * requested parent link is refused.
+ *
+ * A subtask inherits the execution targets its parent already pins (workspace,
+ * agent preset, permission, model) unless the form supplied its own; the
+ * parent human permission confirmation travels with an inherited permission,
+ * so a subtask of an already-confirmed elevated card is runnable at once.
  * @param tasks - current ledger.
- * @param input - raw user input (title/description/prompt + optional schedule).
+ * @param input - raw user input (title/description/prompt + optional schedule/parent).
  * @param now - clock instant (ms epoch).
  * @param id - minted task id.
+ * @param maxSubtaskDepth - deployment subtask depth limit.
  */
 export function applyCreateTask(
   tasks: readonly TaskRecord[],
   input: NewTaskInput,
   now: number,
   id: string,
+  maxSubtaskDepth: number = DEFAULT_SUBTASK_DEPTH,
 ): CreateTaskResult {
-  if (input.title.trim() === '') return { task: undefined, tasks }
-  let task = createTask(input, now, id)
+  if (input.title.trim() === '') return { task: undefined, tasks, error: 'title is required' }
+  const limit = normalizeSubtaskDepth(maxSubtaskDepth)
+  let parent: TaskRecord | undefined
+  if (input.parentId !== undefined) {
+    parent = tasks.find(task => task.id === input.parentId)
+    if (parent === undefined) return { task: undefined, tasks, error: 'parent task not found' }
+    if (parent.archivedAt !== undefined) return { task: undefined, tasks, error: 'parent task is archived' }
+    if (taskDepth(tasks, parent.id) + 1 > limit) {
+      return { task: undefined, tasks, error: `subtask depth limit (${limit}) exceeded` }
+    }
+  }
+  // A subtask copies the execution targets its parent pins so the card shows
+  // what it will run with — EXCEPT the permission. A copied permission would
+  // also have to copy the parent's human confirmation to stay runnable, and the
+  // child would keep both after being detached: one confirmed parent would mint
+  // unbounded confirmed elevated roots. The permission is resolved live from the
+  // attached ancestors at launch instead (see core/subtask.ts), so detaching
+  // removes the inheritance by construction.
+  const effective: NewTaskInput = parent === undefined ? input : {
+    ...input,
+    workspaceId: input.workspaceId ?? parent.workspaceId,
+    mode: input.mode ?? parent.mode,
+    model: input.model ?? parent.model,
+  }
+  let task = createTask(effective, now, id)
   // Arm the requested schedule (new-task dialog): only an enabled rule with
   // a valid cron is applied; blank, invalid, or disabled requests leave the
   // task unscheduled.

package/src/core/use-cases/task-delete.ts

@@ -1,7 +1,11 @@
 /**
  * Delete-task use case: drop a task from the ledger and clear the selection
  * when it pointed at the removed task. Pure ledger transition (no persistence
- * or notify — the controller orchestrates those).
+ * or notify - the controller orchestrates those).
+ *
+ * A task that still has subtasks is refused: deleting the parent would leave
+ * dangling child links, and silently detaching (or cascading) the children is
+ * a data-loss decision the user must make explicitly.
  */
 import type { TaskRecord } from '../tasks.ts'
 
@@ -11,6 +15,8 @@ export interface DeleteTaskResult {
   tasks: readonly TaskRecord[]
   /** Whether the previous selection referenced the removed task. */
   selectionCleared: boolean
+  /** True when the task still carries subtasks, so nothing was removed. */
+  blocked: boolean
 }
 
 /**
@@ -25,9 +31,13 @@ export function applyDeleteTask(
   selectedTaskId: string | undefined,
   id: string,
 ): DeleteTaskResult {
+  if (tasks.some(task => task.parentId === id)) {
+    return { tasks, selectionCleared: false, blocked: true }
+  }
   const next = tasks.filter(task => task.id !== id)
   return {
     tasks: next,
     selectionCleared: selectedTaskId === id,
+    blocked: false,
   }
 }

package/src/core/use-cases/task-parent.ts

@@ -0,0 +1,64 @@
+/**
+ * Parent-link use case: attach an existing on-board task under another as a
+ * subtask, or detach it back to the root. The lineage gate is the same one
+ * creation uses (unknown or archived parent, self, cycle, depth), so the two
+ * ways into the tree cannot disagree. Pure ledger transition.
+ */
+import { DEFAULT_SUBTASK_DEPTH, checkParentLink, normalizeSubtaskDepth, type ParentLinkRejection } from '../subtask.ts'
+import type { TaskRecord } from '../tasks.ts'
+
+/** Result of a parent-link transition. */
+export interface SetParentResult {
+  /** The next ledger; the input reference when refused. */
+  tasks: readonly TaskRecord[]
+  /** Whether the link (or the detachment) was stored. */
+  applied: boolean
+  /** User-facing refusal reason; absent when applied. */
+  error?: string
+}
+
+/** Host error text per refusal reason (the wire carries the same strings). */
+const REJECTION_TEXT: Record<ParentLinkRejection, string> = {
+  'unknown-task': 'task not found',
+  'unknown-parent': 'parent task not found',
+  'archived-parent': 'parent task is archived',
+  'self-parent': 'a task cannot be its own parent',
+  'cycle': 'a task cannot be attached under its own subtask',
+  'depth-exceeded': 'subtask depth limit exceeded',
+}
+
+/**
+ * Attach or detach one task. A null (or blank) parent detaches, which is always
+ * allowed for a known on-board task; attaching validates the whole chain so a
+ * cyclic or too-deep ledger can never be stored.
+ * @param tasks - current ledger.
+ * @param id - the task being moved.
+ * @param parentId - the new parent, or null to detach.
+ * @param now - clock instant (ms epoch).
+ * @param maxSubtaskDepth - deployment subtask depth limit.
+ */
+export function applySetParent(
+  tasks: readonly TaskRecord[],
+  id: string,
+  parentId: string | null,
+  now: number,
+  maxSubtaskDepth: number = DEFAULT_SUBTASK_DEPTH,
+): SetParentResult {
+  const task = tasks.find(candidate => candidate.id === id)
+  if (task === undefined) return { tasks, applied: false, error: REJECTION_TEXT['unknown-task'] }
+  if (task.archivedAt !== undefined) return { tasks, applied: false, error: 'archived task is read-only' }
+  // A task with an open execution may be a participant of a running cascade.
+  // Moving it would break that group's parent walk and leave the parent card
+  // in the running column forever, so the link is frozen until it settles.
+  if (task.status === 'running' || task.executions.some(execution => execution.endedAt === undefined)) {
+    return { tasks, applied: false, error: 'running task cannot be re-parented' }
+  }
+  const check = checkParentLink(tasks, id, parentId, normalizeSubtaskDepth(maxSubtaskDepth))
+  if (!check.ok) return { tasks, applied: false, error: REJECTION_TEXT[check.reason ?? 'unknown-task'] }
+  const nextParentId = parentId === null || parentId === '' ? undefined : parentId
+  if (nextParentId === task.parentId) return { tasks: [...tasks], applied: true }
+  return {
+    tasks: tasks.map(candidate => candidate.id === id ? { ...candidate, parentId: nextParentId, updatedAt: now } : candidate),
+    applied: true,
+  }
+}

package/src/core/use-cases/task-update.ts

@@ -16,7 +16,7 @@ import type { TaskHandoverInput } from '../handover.ts'
  * Editable fields on a task (the update patch surface). `freeze` replaces the
  * continuation-card snapshot (restamping frozenAt); an explicit null clears it.
  */
-export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt' | 'workspaceId' | 'mode' | 'permission' | 'model' | 'reuseSession'>> & {
+export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt' | 'workspaceId' | 'mode' | 'permission' | 'model' | 'reuseSession' | 'teamRun'>> & {
   freeze?: FreezeSnapshot & { redacted?: boolean } | null
   /** Replaces the handover bundle (restamping bundledAt); an explicit null clears it. */
   handover?: TaskHandoverInput | null
@@ -106,6 +106,8 @@ export function applyUpdateTask(
     // Session reuse is a boolean opt-in; false (or an explicit null from a
     // caller that needs to clear it) returns the task to one session per run.
     if ('reuseSession' in patch) next.reuseSession = patch.reuseSession === true ? true : undefined
+    // Team execution is a boolean opt-in with the same clear-by-false rule.
+    if ('teamRun' in patch) next.teamRun = patch.teamRun === true ? true : undefined
     if (workspaceId !== undefined || 'workspaceId' in patch) next.workspaceId = workspaceId
     if (mode !== undefined || 'mode' in patch) next.mode = mode
     if (permission !== undefined || 'permission' in patch) next.permission = permission