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

package/src/host-runner.ts

@@ -60,6 +60,17 @@ function isDefinitionWithdrawn(error: unknown): boolean {
 
 const SERVICE_UNAVAILABLE_ATTEMPTS = 5
 const SERVICE_UNAVAILABLE_BACKOFF_MS = 2_000
+/**
+ * Largest number of history pages one inspection walks back. A session whose
+ * window is wider than this cannot be resolved from its log, which the caller
+ * treats as an unreadable history rather than as pending work.
+ */
+const HISTORY_PAGE_LIMIT = 100
+
+/** One-line text of a gateway or stream failure, for a decideable reason. */
+function failureText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
 
 function delay(ms: number): Promise<void> {
   return new Promise(resolve => { setTimeout(resolve, ms) })
@@ -87,7 +98,14 @@ export interface SessionCommandDispatcher {
 }
 
 export type ExecutionInspection =
-  | { outcome: 'pending' }
+  /**
+   * No verdict yet. `unreadable` separates "the work may still be in progress"
+   * from "this session's history could not be read at all": a reader failure is
+   * not progress, and the caller decides how long to keep waiting before it
+   * reports the execution as undeterminable instead of holding a card open
+   * forever.
+   */
+  | { outcome: 'pending'; unreadable?: true; reason?: string }
   | { outcome: 'succeeded' }
   | { outcome: 'failed'; error: string }
   | { outcome: 'cancelled'; error: string }
@@ -136,6 +154,13 @@ export interface PromptContext {
   peers?: readonly PromptPeer[]
   /** True when those members run as teammates inside this session (Team Lead). */
   team?: boolean
+  /**
+   * Scheduled-run provenance: the instant the cron rule actually fired and the
+   * IANA zone its wall clock was read in. Present only for a cron-triggered
+   * run, so the model can resolve an unqualified date in the run's own terms
+   * instead of guessing from the Host clock (issue #1722).
+   */
+  schedule?: { triggeredAt: number; timeZone: string; cron: string }
 }
 
 /**
@@ -147,13 +172,27 @@ 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)}）`)
+    const lines = peers.map(peer => `- ${escapeProvenanceDelimiter(peer.title)}（teammate: ${peer.name ?? teammateName(peer.title, peer.id, 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')}`
 }
 
+/**
+ * The scheduled-run section: this execution was triggered by the card's cron
+ * rule rather than by a person. It states the firing instant, the rule's zone,
+ * and the rule text, so the run's own clock is unambiguous — the board's
+ * scheduler fires on a wall clock in a specific IANA zone, which is not
+ * necessarily the zone of whatever session the run lands in.
+ */
+function schedulePromptPreamble(context: PromptContext): string | undefined {
+  const schedule = context.schedule
+  if (schedule === undefined) return undefined
+  const stamp = new Date(schedule.triggeredAt).toISOString()
+  return `本次执行由任务看板的定时规则自动触发：触发时间 ${stamp}（UTC），规则时区 ${schedule.timeZone}，cron 表达式 ${schedule.cron}。需要判断「今天」「现在」或计算时间窗口时，以该时区的触发时间为准。`
+}
+
 /**
  * Build the execution prompt for one task.
  * @param task - the task being launched.
@@ -167,11 +206,14 @@ export function promptText(task: TaskRecord, context: PromptContext = {}): strin
     ? undefined
     : `交接包引用（来自任务看板续接卡片，冻结于 ${new Date(handover.bundledAt).toISOString()}）：\n${handover.references.map(reference => `- ${reference}`).join('\n')}`
   // Tag prompts come first: they are the run's standing context (business line,
-  // output location), the handover preamble is a per-card note, and the task
-  // body is the instruction itself.
+  // output location), the handover preamble is a per-card note, the scheduled
+  // section states why this run exists, and the task body is the instruction.
   const tagPreamble = tagPromptPreamble(task)
+  const handoverSection = handoverPreamble
+  const schedulePreamble = schedulePromptPreamble(context)
   const runPreamble = peerPromptPreamble(context)
-  const preambles = [tagPreamble, handoverPreamble, runPreamble].filter((part): part is string => part !== undefined)
+  const preambles = [tagPreamble, handoverSection, schedulePreamble, 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) {
@@ -182,6 +224,27 @@ export function promptText(task: TaskRecord, context: PromptContext = {}): strin
   return preamble === undefined ? declaration : `${preamble}\n\n${declaration}`
 }
 
+/**
+ * The parts of an objective the built-in `/goal` command reads as an operation
+ * rather than as an objective: an exact `clear`/`pause`/`resume`/`edit`
+ * (case-insensitive) and a leading `edit <objective>`.
+ */
+const GOAL_COMMAND_KEYWORD = /^(?:clear|pause|resume|edit)$|^edit\s/i
+
+/**
+ * Build the objective the built-in `/goal` command receives. A prompt whose
+ * text would be read as a goal operation is prefixed with a neutral label: the
+ * instruction stays intact, and the command arms an objective instead of
+ * clearing, pausing, or editing an unrelated goal (or refusing for a missing
+ * one).
+ * @param prompt - the composed execution prompt.
+ * @returns the objective text for `/goal <objective>`.
+ */
+export function goalObjective(prompt: string): string {
+  const text = prompt.trim()
+  return GOAL_COMMAND_KEYWORD.test(text) ? `Goal: ${text}` : text
+}
+
 /**
  * Build the tag section of the execution prompt (issue #1521). Only tags with
  * a non-blank `promptPrefix` contribute; a task whose tags are all bare names
@@ -393,6 +456,82 @@ export class HostExecutionRunner {
       mode: 'queue' as const,
       content: [{ type: 'text' as const, text: promptText(task, context) }],
     })
+    await this.armGoal(sessionId, task, context)
+  }
+
+  /**
+   * Arm dsh's built-in goal on the session. The task prompt is queued FIRST, so
+   * the session's first turn carries the instruction verbatim; `/goal
+   * <objective>` then turns the same text into a persistent objective, and
+   * dsh's goal-round driver keeps starting continuation rounds until the agent
+   * marks it complete (see {@link goalVerdict} for how the run settles).
+   *
+   * Opt-out: a task whose `goalRun` is an explicit false runs one plain turn.
+   * A refusal (no command dispatcher, no `/goal` command in this cohort, an
+   * objective the command rejects) is reported and the run continues as that
+   * plain turn: the task was asked to run, and a missing goal mode must not
+   * lose the work.
+   */
+  private async armGoal(sessionId: ExecutionSessionId, task: TaskRecord, context: PromptContext): Promise<void> {
+    if (task.goalRun === false) return
+    if (this.commands === undefined) {
+      console.warn('[dsh-task-board] no command dispatcher is available; task ' + task.id + ' runs without /goal')
+      return
+    }
+    try {
+      const command = await this.commands.execute(
+        sessionId,
+        '/goal ' + goalObjective(promptText(task, context)),
+        AbortSignal.timeout(30_000),
+      )
+      if (command === undefined) {
+        console.warn('[dsh-task-board] /goal was not acknowledged for session ' + sessionId + '; the run continues as a plain turn')
+        return
+      }
+      if (command.kind !== 'success') {
+        console.warn('[dsh-task-board] /goal was refused for session ' + sessionId + ': ' + (command.text ?? 'no reason reported') + '; the run continues as a plain turn')
+      }
+    } catch (error) {
+      console.warn('[dsh-task-board] could not arm /goal on session ' + sessionId + '; the run continues as a plain turn', error)
+    }
+  }
+
+  /**
+   * The verdict an armed dsh goal imposes on an otherwise completed turn.
+   *
+   * A goal run is one session working many automatic continuation rounds:
+   * dsh's goal-round driver queues the next round whenever the agent goes
+   * idle, so the first completed `turn/end` is not the execution's result.
+   * Settling there would leave the card in `done` while the session keeps
+   * working, and a scheduled task would fire a second, concurrent session.
+   * The session projection is the authority: an `active` goal keeps the
+   * execution pending, a `blocked` goal fails it with the recorded reason, and
+   * any other phase (complete, paused, or no goal at all) leaves the turn
+   * verdict in place.
+   *
+   * An unreadable projection falls back to that turn verdict: a cohort whose
+   * gateway withdrew `session/projections` must not hang every execution.
+   */
+  private async goalVerdict(sessionId: string): Promise<ExecutionInspection | undefined> {
+    let projections: { values?: { goal?: unknown } } | null
+    try {
+      projections = await this.invoke('session', 'projections', { sessionId }) as { values?: { goal?: unknown } } | null
+    } catch (error) {
+      console.warn('[dsh-task-board] session/projections failed while reading the goal phase; settling from the turn result', error)
+      return undefined
+    }
+    const goal = projections?.values?.goal
+    if (goal === undefined || goal === null) return undefined
+    const view = (goal as { goal?: { phase?: unknown; blockedReason?: { message?: unknown } } }).goal
+    if (view?.phase === 'active') return { outcome: 'pending' }
+    if (view?.phase === 'blocked') {
+      const message = view.blockedReason?.message
+      return {
+        outcome: 'failed',
+        error: 'goal is blocked: ' + (typeof message === 'string' && message !== '' ? message : 'no reason recorded'),
+      }
+    }
+    return undefined
   }
 
   async listRunning(): Promise<{ known: true; count: number; items: SessionSummary[] } | { known: false }> {
@@ -424,8 +563,17 @@ export class HostExecutionRunner {
     }
   }
 
-  /** Resolve an execution outcome from the session list and bounded history pages. */
-  async inspect(sessionId: string, startedAt = 0, sessions?: readonly SessionSummary[]): Promise<ExecutionInspection> {
+  /**
+   * Resolve an execution outcome from the session list and bounded history pages.
+   * @param sessionId - the session the execution runs in.
+   * @param startedAt - instant the execution opened; earlier events are not its own.
+   * @param sessions - roster from the caller's own poll, when it already has one.
+   * @param options.whileRunning - read the first completed turn even while the
+   *   roster reports the session as running. A durable Agent Teams teammate
+   *   stays alive after its turn ends, so `running` never clears for it and the
+   *   turn it completed is the only verdict it will ever expose.
+   */
+  async inspect(sessionId: string, startedAt = 0, sessions?: readonly SessionSummary[], options: { whileRunning?: boolean } = {}): Promise<ExecutionInspection> {
     let items: readonly SessionSummary[]
     if (sessions !== undefined) {
       items = sessions
@@ -455,7 +603,7 @@ export class HostExecutionRunner {
       this.scanMemos.delete(sessionId)
       return { outcome: 'cancelled', error: 'execution session no longer exists' }
     }
-    if (summary.running) return { outcome: 'pending' }
+    if (summary.running && options.whileRunning !== true) return { outcome: 'pending' }
 
     let opening: { cursor: number; records: readonly SessionHistoryRecord[]; hasMore: boolean }
     try {
@@ -465,12 +613,12 @@ export class HostExecutionRunner {
       if (typeof iterator.return === 'function') await iterator.return()
       const follow = next.done === true ? undefined : next.value as { type?: string; cursor?: number; records?: readonly SessionHistoryRecord[]; hasMore?: boolean }
       if (follow === undefined || follow.type !== 'snapshot' || typeof follow.cursor !== 'number' || follow.records === undefined || typeof follow.hasMore !== 'boolean') {
-        return { outcome: 'pending' }
+        return { outcome: 'pending', unreadable: true, reason: 'session/follow returned no opening frame' }
       }
       opening = { cursor: follow.cursor, records: follow.records, hasMore: follow.hasMore }
     } catch (error) {
       console.warn('[dsh-task-board] session/follow failed during execution inspection; keeping the outcome pending', error)
-      return { outcome: 'pending' }
+      return { outcome: 'pending', unreadable: true, reason: 'session/follow failed: ' + failureText(error) }
     }
     const openingEvents = opening.records.map(record => ({ event: recordEvent(record) }))
     const newestSeq = openingEvents.reduce<number | undefined>((newest, entry) => newest === undefined ? entry.event.seq : Math.max(newest, entry.event.seq), undefined)
@@ -478,7 +626,7 @@ export class HostExecutionRunner {
     const events: Array<{ event: { type: string; seq: number; time: number; data: unknown } }> = [...openingEvents]
     let beforeSeq: number | undefined
     let reachedExecutionBoundary = !opening.hasMore
-    for (let page = 0; page < 100 && !reachedExecutionBoundary; page += 1) {
+    for (let page = 0; page < HISTORY_PAGE_LIMIT && !reachedExecutionBoundary; page += 1) {
       let history: SessionPage
       try {
         history = await this.invoke('session', 'page', {
@@ -489,7 +637,7 @@ export class HostExecutionRunner {
         }) as SessionPage
       } catch (error) {
         console.warn('[dsh-task-board] session/page failed during execution inspection; keeping the outcome pending', error)
-        return { outcome: 'pending' }
+        return { outcome: 'pending', unreadable: true, reason: 'session/page failed: ' + failureText(error) }
       }
       const pageEntries = pageEvents(history)
       events.push(...pageEntries)
@@ -502,7 +650,9 @@ export class HostExecutionRunner {
       if (oldestSeq === undefined || oldestSeq === beforeSeq) return { outcome: 'pending' }
       beforeSeq = oldestSeq
     }
-    if (!reachedExecutionBoundary) return { outcome: 'pending' }
+    if (!reachedExecutionBoundary) {
+      return { outcome: 'pending', unreadable: true, reason: 'history scan did not reach the execution start within ' + HISTORY_PAGE_LIMIT + ' pages' }
+    }
     const turnEnd = events
       .filter(entry => entry.event.type === 'turn/end' && (startedAt <= 0 || entry.event.time >= startedAt))
       .sort((a, b) => a.event.seq - b.event.seq)[0]
@@ -512,7 +662,7 @@ export class HostExecutionRunner {
     }
     this.scanMemos.delete(sessionId)
     const reason = nonCompletedTurnEnd(turnEnd.event.data)
-    if (reason === undefined) return { outcome: 'succeeded' }
+    if (reason === undefined) return await this.goalVerdict(sessionId) ?? { 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.