@linxin666/dsh-client-ui-task-board 0.4.0 → 0.4.2

package/src/host-runner.ts

@@ -2,6 +2,7 @@ import type { TypertGateway } from '@deepseek-ai/dsh-api-gateway'
 import type { SessionAddress, SessionHistoryRecord, SessionListValue, SessionPage, SessionSummary } from '@deepseek-ai/dsh-api-session-controller/types'
 import type { CommandResult } from '@deepseek-ai/dsh-commands/types'
 import type { Workspace } from '@deepseek-ai/dsh-workspace/types'
+import { teammateName } from './core/subtask.ts'
 import type { TaskPermission, TaskRecord } from './core/tasks.ts'
 
 /** Host services needed to validate a task's workspace before creating a session. */
@@ -45,6 +46,18 @@ function isInvocationUnavailable(error: unknown): boolean {
   return code === 'invocation-unavailable' || code === 'gateway/invocation-unavailable'
 }
 
+/**
+ * Whether the endpoint exists but its strict definition was withdrawn by the
+ * running gateway (the cohort changed under this plugin). The plugin can send
+ * the call correctly and still be refused, and nothing in this repository can
+ * restore the definition, so the roster is treated as unknown quietly instead
+ * of printing an error the user has no action for (#1672).
+ */
+function isDefinitionWithdrawn(error: unknown): boolean {
+  const code = (error as { code?: unknown }).code
+  return code === 'definition-unavailable' || code === 'gateway/definition-unavailable'
+}
+
 const SERVICE_UNAVAILABLE_ATTEMPTS = 5
 const SERVICE_UNAVAILABLE_BACKOFF_MS = 2_000
 
@@ -107,7 +120,47 @@ function escapeProvenanceDelimiter(value: string): string {
  * first, the provenance wrap then encloses the instruction. Plain tasks (no
  * freeze) keep the bare handover preamble + prompt.
  */
-export function promptText(task: TaskRecord): string {
+/** One other execution member of a run, as named in the launched task's prompt. */
+export interface PromptPeer {
+  /** Task id of the member. */
+  id: string
+  /** Member title. */
+  title: string
+  /** Teammate name when this member runs as a teammate. */
+  name?: string
+}
+
+/** Execution-shape context appended to the launched task's prompt. */
+export interface PromptContext {
+  /** The other members this run opens, excluding the launched task itself. */
+  peers?: readonly PromptPeer[]
+  /** True when those members run as teammates inside this session (Team Lead). */
+  team?: boolean
+}
+
+/**
+ * The execution-shape section: what else this run opens. A plain cascade opens
+ * one independent session per member; a team run starts every other member as a
+ * teammate inside THIS session, so the prompt names the Team tools instead.
+ */
+function peerPromptPreamble(context: PromptContext): string | undefined {
+  const peers = context.peers ?? []
+  if (peers.length === 0) return undefined
+  if (context.team === true) {
+    const lines = peers.map(peer => `- ${escapeProvenanceDelimiter(peer.title)}（teammate: ${peer.name ?? teammateName(peer.title, peer.id)}）`)
+    return `本任务是 Agent Team 的 Lead：本次运行不额外开启独立会话，以下 ${peers.length} 个子任务成员已在本会话中作为 teammate 启动。用 list_agents / send_message / wait_agent 协调它们，用任务看板工具读写它们在看板上的卡片：\n${lines.join('\n')}`
+  }
+  const lines = peers.map(peer => `- ${escapeProvenanceDelimiter(peer.title)}（任务 ${peer.id}）`)
+  return `本次运行同时并发开启 ${peers.length} 个独立 DSH 会话执行下列子任务成员（可用 task_board_* 工具查看它们的进度）：\n${lines.join('\n')}`
+}
+
+/**
+ * Build the execution prompt for one task.
+ * @param task - the task being launched.
+ * @param context - the run's other members, for the execution-shape section.
+ * @returns the prompt text.
+ */
+export function promptText(task: TaskRecord, context: PromptContext = {}): string {
   const body = task.prompt !== '' ? task.prompt : task.title
   const handover = task.handover
   const handoverPreamble = handover === undefined || handover.references.length === 0
@@ -117,7 +170,8 @@ export function promptText(task: TaskRecord): string {
   // output location), the handover preamble is a per-card note, and the task
   // body is the instruction itself.
   const tagPreamble = tagPromptPreamble(task)
-  const preambles = [tagPreamble, handoverPreamble].filter((part): part is string => part !== undefined)
+  const runPreamble = peerPromptPreamble(context)
+  const preambles = [tagPreamble, handoverPreamble, runPreamble].filter((part): part is string => part !== undefined)
   const preamble = preambles.length === 0 ? undefined : preambles.join('\n\n')
   const freeze = task.freeze
   if (freeze === undefined) {
@@ -145,10 +199,27 @@ function tagPromptPreamble(task: TaskRecord): string | undefined {
   return `标签提示（任务看板标签，每次执行前注入）：\n${lines.join('\n')}`
 }
 
-function isErrorTurnEnd(data: unknown): boolean {
-  if (typeof data !== 'object' || data === null) return false
+/**
+ * Why a `turn/end` did not complete successfully, or undefined when it did.
+ *
+ * The harness treats exactly `completed` as success (`headless` maps the turn
+ * reason to its exit code, `subagent/projection` records `lastTurnCompleted`,
+ * and `max-tokens` is a ceiling, not a result). A task-board execution is a
+ * SUCCESS only on positive evidence of a completed turn; every other reason —
+ * and an unreadable one — must be reported, or the board stamps a failed run
+ * as `succeeded` and a schedule dies silently (issue #1708). `interrupted` is
+ * the reason a restart produces: `interruptedTurnClosers` synthesizes it for a
+ * log whose tail turn never ended, which is exactly an aborted resume.
+ * @param data - the `turn/end` event payload.
+ * @returns the reason kind when it is not `completed`, else undefined.
+ */
+function nonCompletedTurnEnd(data: unknown): string | undefined {
+  if (typeof data !== 'object' || data === null) return 'unknown'
   const reason = (data as { reason?: unknown }).reason
-  return typeof reason === 'object' && reason !== null && (reason as { kind?: unknown }).kind === 'error'
+  if (typeof reason !== 'object' || reason === null) return 'unknown'
+  const kind = (reason as { kind?: unknown }).kind
+  if (typeof kind !== 'string') return 'unknown'
+  return kind === 'completed' ? undefined : kind
 }
 
 /**
@@ -204,7 +275,7 @@ export class HostExecutionRunner {
    * @param options - optional session to continue in.
    * @returns the session id the execution runs in.
    */
-  async launch(task: TaskRecord, options: { reuseSessionId?: string } = {}): Promise<string> {
+  async launch(task: TaskRecord, options: { reuseSessionId?: string; promptContext?: PromptContext } = {}): Promise<string> {
     // A handover bundle overrides the legacy pin fields: the bundle is the
     // authoritative execution triplet for a continuation card (issue #5).
     const workspaceId = task.handover?.workspaceId ?? task.workspaceId
@@ -227,7 +298,16 @@ export class HostExecutionRunner {
     const reused = options.reuseSessionId as ExecutionSessionId | undefined
     if (reused !== undefined) {
       try {
-        await this.pinAndPrompt(reused, task, permission)
+        // Assert the pinned preset against the one the session records before
+        // prompting. The reuse path must not call `session/create` (that would
+        // create or re-adopt a session the board only meant to continue), so
+        // the recorded preset is read through `session/projections` — the
+        // documented read that resolves NO Agent — and compared here. A card
+        // whose session was composed from a different preset now fails closed
+        // instead of silently running under the wrong composition, matching
+        // the fresh branch's `agentPreset` assertion (issue #1708).
+        await this.assertReusedPreset(reused, mode)
+        await this.pinAndPrompt(reused, task, permission, options.promptContext)
       } catch (error) {
         throw new SessionLaunchError(reused, error)
       }
@@ -240,19 +320,52 @@ export class HostExecutionRunner {
     const sessionId = created.sessionId
     try {
       await this.invoke('session', 'rename', { sessionId, title: task.title })
-      await this.pinAndPrompt(sessionId, task, permission)
+      await this.pinAndPrompt(sessionId, task, permission, options.promptContext)
     } catch (error) {
       throw new SessionLaunchError(sessionId, error)
     }
     return sessionId
   }
 
+  /**
+   * Fail closed when a reused session records a different Agent preset than
+   * the one this task pins.
+   *
+   * The fresh branch asserts the pin by passing `agentPreset` to
+   * `session/create`; the reuse branch must not call that method (it would
+   * create or re-adopt the very session the board only meant to continue), so
+   * the recorded value is read through `session/projections` — the documented
+   * read that resolves no Agent — and compared here (issue #1708). A session
+   * whose preset cannot be read is not treated as a match: silently continuing
+   * under an unknown composition is the failure this guards.
+   * @param sessionId - the session this execution continues in.
+   * @param pinned - the preset id the task pins, when it pins one.
+   */
+  private async assertReusedPreset(sessionId: ExecutionSessionId, pinned: string | undefined): Promise<void> {
+    if (pinned === undefined) return
+    const projections = await this.invoke('session', 'projections', { sessionId }) as
+      | { values?: { agentPreset?: unknown } }
+      | null
+    const recorded = projections?.values?.agentPreset
+    if (recorded === pinned) return
+    throw new Error(
+      'reused session ' + sessionId + ' was composed from agent preset '
+      + (typeof recorded === 'string' ? '"' + recorded + '"' : 'an unreadable value')
+      + ', but the task pins "' + pinned + '"',
+    )
+  }
+
   /**
    * Re-assert the pinned execution contract on a session and queue the task
    * prompt. Shared by the fresh-session and reuse paths so both apply exactly
    * the same permission/model pins before the prompt.
    */
-  private async pinAndPrompt(sessionId: ExecutionSessionId, task: TaskRecord, permission: TaskPermission | undefined): Promise<void> {
+  private async pinAndPrompt(
+    sessionId: ExecutionSessionId,
+    task: TaskRecord,
+    permission: TaskPermission | undefined,
+    context: PromptContext = {},
+  ): Promise<void> {
     if (permission !== undefined) {
       if (this.commands === undefined) throw new Error('permission command dispatcher is unavailable')
       const command = await this.commands.execute(sessionId, '/permission ' + permission, AbortSignal.timeout(30_000))
@@ -278,7 +391,7 @@ export class HostExecutionRunner {
       sessionId,
       requestId: 'task-board-' + crypto.randomUUID(),
       mode: 'queue' as const,
-      content: [{ type: 'text' as const, text: promptText(task) }],
+      content: [{ type: 'text' as const, text: promptText(task, context) }],
     })
   }
 
@@ -295,6 +408,13 @@ export class HostExecutionRunner {
           }
           return { known: false }
         }
+        if (isDefinitionWithdrawn(error)) {
+          if (!this.unsupportedSessionListWarned) {
+            this.unsupportedSessionListWarned = true
+            console.warn('[dsh-task-board] the host gateway withdrew the session/list definition for this DSH cohort; task board roster auto-discovery is disabled', error)
+          }
+          return { known: false }
+        }
         if (!isServiceUnavailable(error) || attempt >= this.unavailableAttempts) {
           console.error('[dsh-task-board] session/list failed; treating the host session roster as unknown', error)
           return { known: false }
@@ -321,6 +441,10 @@ export class HostExecutionRunner {
           }
           return { outcome: 'pending' }
         }
+        if (isDefinitionWithdrawn(error)) {
+          console.warn('[dsh-task-board] the host gateway withdrew the session/list definition for this DSH cohort; keeping the outcome pending', error)
+          return { outcome: 'pending' }
+        }
         console.warn('[dsh-task-board] session/list failed during execution inspection; keeping the outcome pending', error)
         return { outcome: 'pending' }
       }
@@ -387,8 +511,13 @@ export class HostExecutionRunner {
       return { outcome: 'pending' }
     }
     this.scanMemos.delete(sessionId)
-    return isErrorTurnEnd(turnEnd.event.data)
+    const reason = nonCompletedTurnEnd(turnEnd.event.data)
+    if (reason === undefined) return { outcome: 'succeeded' }
+    // `error` keeps its historical wording; every other non-completed reason
+    // (aborted / blocked / max-tokens / interrupted) now reports instead of
+    // silently counting as success.
+    return reason === 'error'
       ? { outcome: 'failed', error: 'agent turn ended with an error' }
-      : { outcome: 'succeeded' }
+      : { outcome: 'failed', error: 'agent turn ended without completing: ' + reason }
   }
 }

package/src/host-service.ts

@@ -2,11 +2,42 @@ import type { TypertGateway } from '@deepseek-ai/dsh-api-gateway'
 import { nextRunAtMs } from './core/schedule.ts'
 import { reusableSessionId } from './core/session-reuse.ts'
 import { HostTaskLedger, type OpenedRun, type OpenExecutionReference } from './host-ledger.ts'
-import { HostExecutionRunner, SessionLaunchError, type SessionCommandDispatcher, type SessionSummary, type TaskBoardWorkspaceRegistry } from './host-runner.ts'
+import { HostExecutionRunner, SessionLaunchError, promptText, type SessionCommandDispatcher, type SessionSummary, type TaskBoardWorkspaceRegistry } from './host-runner.ts'
+import { teammateName } from './core/subtask.ts'
 import { PowerInhibitor } from './power-inhibitor.ts'
 import { TASK_BOARD_SCHEMA_VERSION, type TaskBoardAction, type TaskBoardEventPayload, type TaskBoardSnapshot } from './protocol.ts'
 import type { TaskPermission } from './core/handover.ts'
 
+/** One teammate the Host asks the Agent Teams service to spawn for a team run. */
+export interface TeamSpawnInput {
+  /** Session id of the run's Team Lead (the root task's execution session). */
+  leadSessionId: string
+  /** Immutable lower-kebab-case teammate name, unique inside the Team. */
+  name: string
+  /** Short description of the delegated responsibility. */
+  description: string
+  /** The subtask's execution prompt. */
+  prompt: string
+}
+
+/** Result of one teammate spawn attempt. */
+export interface TeamSpawnResult {
+  /** The teammate's session id when it reached the active edge. */
+  sessionId?: string
+  /** Why the spawn failed: a thrown call, or a member that settled as failed. */
+  error?: string
+}
+
+/**
+ * The Agent Teams capability the Host needs for team-mode runs. The plugin
+ * builds it from the optional `agentTeams` service; it is absent when this
+ * deployment does not serve that service, in which case a team run is refused
+ * instead of silently degrading into a plain cascade.
+ */
+export interface TaskBoardTeamDispatcher {
+  spawn(input: TeamSpawnInput): Promise<TeamSpawnResult>
+}
+
 const SESSION_POLL_MS = 5_000
 const SCHEDULE_TICK_MS = 30_000
 const RESUME_GAP_MS = SCHEDULE_TICK_MS + 15_000
@@ -30,6 +61,7 @@ export class TaskBoardHostService {
    */
   private idleSessionIds: ReadonlySet<string> | undefined
   private preventIdleSleep = false
+  private readonly team: TaskBoardTeamDispatcher | undefined
   private lastPowerJson = ''
   private readonly now: () => number
 
@@ -40,9 +72,15 @@ export class TaskBoardHostService {
     commandDispatcher?: SessionCommandDispatcher
     workspaceRegistry?: TaskBoardWorkspaceRegistry
     sessionDefaultPermission?: TaskPermission
+    maxSubtaskDepth?: number
+    team?: TaskBoardTeamDispatcher
   } = {}) {
-    this.ledger = options.ledger ?? new HostTaskLedger(undefined, undefined, { sessionDefaultPermission: options.sessionDefaultPermission })
+    this.ledger = options.ledger ?? new HostTaskLedger(undefined, undefined, {
+      sessionDefaultPermission: options.sessionDefaultPermission,
+      maxSubtaskDepth: options.maxSubtaskDepth,
+    })
     this.runner = new HostExecutionRunner(gateway, options.commandDispatcher, options.workspaceRegistry)
+    this.team = options.team
     this.power = options.power ?? new PowerInhibitor()
     this.now = options.now ?? Date.now
     installStreamErrorGuards()
@@ -99,6 +137,8 @@ export class TaskBoardHostService {
       scheduler: state.scheduler,
       power: this.power.snapshot(),
       sessionDefaultPermission: this.ledger.sessionDefaultPermission,
+      maxSubtaskDepth: this.ledger.maxSubtaskDepth,
+      teamRunAvailable: this.team !== undefined,
     }
   }
 
@@ -115,8 +155,15 @@ export class TaskBoardHostService {
 
   apply(requestId: string, action: TaskBoardAction, initiator?: string): TaskBoardSnapshot {
     if (!this.active) throw new Error('task board is disabled')
+    // Fail closed before the ledger opens anything: a card opted into team
+    // execution cannot run in a deployment that serves no Agent Teams service,
+    // and silently degrading it to a plain cascade would misreport the work.
+    if (this.team === undefined && (action.kind === 'run' || action.kind === 'rerun')) {
+      const task = this.ledger.state().tasks.find(item => item.id === action.taskId)
+      if (task?.teamRun === true) throw new Error('Agent Teams is unavailable in this deployment')
+    }
     const result = this.ledger.applyRequest(requestId, action, initiator)
-    if (result.run !== undefined) this.scheduleLaunch(result.run)
+    if (result.runs !== undefined) this.dispatchRuns(result.runs)
     return {
       schemaVersion: TASK_BOARD_SCHEMA_VERSION,
       revision: result.state.revision,
@@ -134,11 +181,29 @@ export class TaskBoardHostService {
     this.listeners.clear()
   }
 
-  private async launch(opened: OpenedRun): Promise<void> {
+  private async launch(opened: OpenedRun, others: readonly OpenedRun[] = []): Promise<void> {
     try {
-      const reuseSessionId = reusableSessionId(opened.task, this.idleSessionIds)
-      const sessionId = await this.runner.launch(opened.task, reuseSessionId === undefined ? {} : { reuseSessionId })
+      // A team run always mints a fresh Lead session: teammates are immutable
+      // children of that session, so reusing an older one would collide on
+      // their names and orphan the previous team.
+      const team = opened.task.teamRun === true
+      const reuseSessionId = team ? undefined : reusableSessionId(opened.task, this.idleSessionIds)
+      // Both modes tell the launched agent what else this run opens; only a team
+      // run names teammates, because only then does this session own them.
+      const promptContext = others.length === 0 ? undefined : {
+        peers: others.map(other => ({
+          id: other.task.id,
+          title: other.task.title,
+          ...(team ? { name: teammateName(other.task.title, other.execution.runGroupId ?? other.task.id) } : {}),
+        })),
+        ...(team ? { team: true } : {}),
+      }
+      const sessionId = await this.runner.launch(opened.task, {
+        ...(reuseSessionId === undefined ? {} : { reuseSessionId }),
+        ...(promptContext === undefined ? {} : { promptContext }),
+      })
       this.ledger.attachSession(opened.task.id, opened.execution.id, sessionId)
+      if (team) for (const teammate of others) this.scheduleTeammate(teammate, sessionId)
     } catch (error) {
       if (error instanceof SessionLaunchError) {
         this.ledger.attachSession(opened.task.id, opened.execution.id, error.sessionId)
@@ -147,6 +212,42 @@ export class TaskBoardHostService {
     }
   }
 
+  private scheduleTeammate(opened: OpenedRun, leadSessionId: string): void {
+    void this.spawnTeammate(opened, leadSessionId).catch(error => {
+      safeConsoleError('[dsh-task-board] teammate spawn settlement failed', error)
+    })
+  }
+
+  /**
+   * Spawn one teammate inside the Lead session and attach the teammate's
+   * session to the subtask execution, so the existing session monitor settles
+   * it from the teammate's own turn like any other execution. A spawn that
+   * fails settles the subtask as failed immediately, which then folds into the
+   * Lead's cascade verdict.
+   */
+  private async spawnTeammate(opened: OpenedRun, leadSessionId: string): Promise<void> {
+    const team = this.team
+    if (team === undefined) {
+      this.ledger.settle(opened.task.id, opened.execution.id, 'failed', 'Agent Teams is unavailable in this deployment')
+      return
+    }
+    try {
+      const member = await team.spawn({
+        leadSessionId,
+        name: teammateName(opened.task.title, opened.execution.runGroupId ?? opened.task.id),
+        description: opened.task.title,
+        prompt: promptText(opened.task),
+      })
+      if (member.sessionId === undefined || member.sessionId === '') {
+        this.ledger.settle(opened.task.id, opened.execution.id, 'failed', member.error ?? 'teammate provisioning failed')
+        return
+      }
+      this.ledger.attachSession(opened.task.id, opened.execution.id, member.sessionId)
+    } catch (error) {
+      this.ledger.settle(opened.task.id, opened.execution.id, 'failed', error instanceof Error ? error.message : String(error))
+    }
+  }
+
   private async pollSessions(): Promise<void> {
     if (this.disposed) return
     if (!this.active && this.ledger.runtimeView().openExecutions.length === 0) return
@@ -204,8 +305,7 @@ export class TaskBoardHostService {
     }
     for (const schedule of this.ledger.dueSchedules(now)) {
       const next = nextRunAtMs(schedule.cron, schedule.nextRunAt)
-      const opened = this.ledger.openScheduled(schedule.taskId, next, now)
-      if (opened !== undefined) this.scheduleLaunch(opened)
+      this.dispatchRuns(this.ledger.openScheduled(schedule.taskId, next, now))
     }
   }
 
@@ -213,8 +313,25 @@ export class TaskBoardHostService {
     return this.ledger.armedScheduleCount()
   }
 
-  private scheduleLaunch(opened: OpenedRun): void {
-    void this.launch(opened).catch(error => {
+  /**
+   * Launch one run set. The root goes first and receives the run shape in its
+   * prompt (which members this run opens, and how they run); every plain-cascade
+   * member then launches on its own so one refused participant cannot hold the
+   * others back. A team run's members are spawned inside the root's Lead
+   * session instead, once that session exists.
+   */
+  private dispatchRuns(runs: readonly OpenedRun[]): void {
+    if (runs.length === 0) return
+    const root = runs.find(run => run.dispatch !== 'teammate') ?? runs[0]
+    const others = runs.filter(run => run !== root)
+    this.scheduleLaunch(root, others)
+    for (const run of others) {
+      if (run.dispatch !== 'teammate') this.scheduleLaunch(run)
+    }
+  }
+
+  private scheduleLaunch(opened: OpenedRun, others: readonly OpenedRun[] = []): void {
+    void this.launch(opened, others).catch(error => {
       safeConsoleError('[dsh-task-board] execution launch settlement failed', error)
     })
   }