jackherd 1.8.1 → 1.9.0

package/src/watch/task-parallel.ts

@@ -0,0 +1,206 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+
+export const TASK_PARALLEL_EVENT = 'parallel tasks'
+
+/** A proposal for the non-stream watcher: the line `formatTaskParallelLine` made for `lane`. */
+export type TaskParallelEvent = { kind: typeof TASK_PARALLEL_EVENT; lane: string; line: string }
+
+/** Lane → the fingerprint last seen at a heartbeat; a lane without an entry has had none. */
+export type TaskParallelFingerprints = Record<string, string>
+
+export const isTaskParallelFingerprints = (value: unknown): value is TaskParallelFingerprints =>
+  typeof value === 'object' &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.values(value).every((entry) => typeof entry === 'string')
+
+export type OpenTask = { text: string; phase: string }
+
+/** One agent's recent work: the files it touched, its active task text and phase when the signal names them. */
+export type ActiveWork = { name: string; files: string[]; taskText?: string; phase?: string }
+
+export type TaskParallelInput = {
+  lane: string
+  open: OpenTask[]
+  active: ActiveWork[]
+  /** Phase id → the paths of its writes cell; `''` is the whole repository. Absent for a phase without one. */
+  phaseWrites: Record<string, string[]>
+  doneCount: number
+  /** Tokens a fresh agent costs before it does anything, measured by the caller. */
+  baselineTokens: number
+  /** A proposal is made only when the estimate stays below this. */
+  thresholdTokens: number
+}
+
+export type TaskParallelResult =
+  | { proposed: false; reason: string }
+  | {
+      proposed: true
+      tasks: OpenTask[]
+      waiting: number
+      extraAgents: number
+      estimateTokens: number
+      reason: string
+    }
+
+export type TaskParallelProposal = Extract<TaskParallelResult, { proposed: true }>
+
+const MIN_TASKS_BESIDE_AGENT = 1
+const MIN_TASKS_WITHOUT_AGENT = 2
+const TEXT_LIMIT = 60
+const TOKENS_PER_K = 1000
+const GLOB_CHARACTER = /[*?[{]/
+const LINE_SUFFIX = /(?::\d+(?:[-:]\d+)*|#L\d+.*)$/
+const PATH_EXTENSIONS = 'ts|tsx|js|mjs|json|md|sh|yml|yaml|css|html|toml|sql'
+const BARE_FILE = new RegExp(`(?<![\\w./\`-])[\\w./-]+\\.(?:${PATH_EXTENSIONS})(?::\\d+(?:[-:]\\d+)*)?(?![\\w/])`, 'g')
+const BACKTICKED = /`([^`]+)`/g
+const FILE_LIKE = new RegExp(`/|\\.(?:${PATH_EXTENSIONS})$|^\\.[\\w-]+`)
+
+const normalise = (entry: string): string | null => {
+  const trimmed = entry.trim()
+  if (trimmed === '' || /\s/.test(trimmed)) return null
+  const path = trimmed.replace(LINE_SUFFIX, '').replace(/^\.\//, '').replace(/\/+$/, '')
+  return FILE_LIKE.test(path) && path !== '' ? path : null
+}
+
+/**
+ * The paths a task line names: backticked entries that look like a path or file name and bare file names with a known
+ * extension. `:line` suffixes and `./` are cut, globs stay globs, duplicates drop. A task naming none is unknown, and
+ * unknown is never proposed.
+ */
+export const pathsOfTask = (text: string): string[] => {
+  const backticked = [...text.matchAll(BACKTICKED)].map((match) => match[1] ?? '')
+  const bare = text.replace(BACKTICKED, ' ').match(BARE_FILE) ?? []
+  return [...new Set([...backticked, ...bare].map(normalise).filter((path): path is string => path !== null))]
+}
+
+const literalPrefix = (path: string): string => {
+  const glob = path.search(GLOB_CHARACTER)
+  return glob === -1 ? path : path.slice(0, Math.max(path.lastIndexOf('/', glob), 0))
+}
+
+const isInside = (inner: string, outer: string): boolean =>
+  outer === '' || inner === outer || inner.startsWith(`${outer}/`)
+
+const holdsName = (name: string, path: string): boolean => `/${path}/`.includes(`/${name}/`) || path === name
+
+/**
+ * Whether two paths may touch the same files. Directories contain what lies below them, a glob stands for the
+ * directory its literal part ends in, `''` is the whole repository, and a bare name matches that name in any directory.
+ * When unsure the answer is yes.
+ */
+export const pathsOverlap = (left: string, right: string): boolean => {
+  const [a, b] = [literalPrefix(left), literalPrefix(right)]
+  const bareLeft = !left.includes('/') && !GLOB_CHARACTER.test(left) && left !== ''
+  const bareRight = !right.includes('/') && !GLOB_CHARACTER.test(right) && right !== ''
+  if (bareLeft || bareRight) {
+    const [name, other] = bareLeft ? [left, right] : [right, left]
+    return GLOB_CHARACTER.test(other) ? true : other === '' || holdsName(name, other)
+  }
+  return isInside(a, b) || isInside(b, a)
+}
+
+const clash = (left: readonly string[], right: readonly string[]): boolean =>
+  left.some((a) => right.some((b) => pathsOverlap(a, b)))
+
+const activeFootprint = (input: TaskParallelInput): string[] =>
+  input.active.flatMap((work) => [
+    ...work.files,
+    ...pathsOfTask(work.taskText ?? ''),
+    ...(work.phase === undefined ? [] : (input.phaseWrites[work.phase] ?? [])),
+  ])
+
+const estimateTokens = (input: TaskParallelInput, taskCount: number): { extraAgents: number; tokens: number } => {
+  const extraAgents = input.active.length > 0 ? taskCount : taskCount - 1
+  return { extraAgents, tokens: input.baselineTokens * extraAgents }
+}
+
+const kilo = (tokens: number): string => `${Math.round(tokens / TOKENS_PER_K)}k`
+
+/** The first group of open tasks, in plan order, whose paths clash neither with the running work nor with each other. */
+const parallelGroup = (input: TaskParallelInput): OpenTask[] => {
+  const running = activeFootprint(input)
+  const chosen: { task: OpenTask; paths: string[] }[] = []
+  for (const task of input.open) {
+    const paths = pathsOfTask(task.text)
+    const free = paths.length > 0 && !clash(paths, running) && chosen.every((other) => !clash(paths, other.paths))
+    if (free) chosen.push({ task, paths })
+  }
+  return chosen.map(({ task }) => task)
+}
+
+/**
+ * Open tasks that could start now beside the running work: no path overlap with it or with each other, none without a
+ * named path. Proposed for one task beside running work or two tasks without, and when the baseline cost of the extra agents stays below the
+ * threshold; the reason says in plain words which way it went.
+ */
+export const proposeTaskParallel = (input: TaskParallelInput): TaskParallelResult => {
+  const tasks = parallelGroup(input)
+  const needed = input.active.length > 0 ? MIN_TASKS_BESIDE_AGENT : MIN_TASKS_WITHOUT_AGENT
+  if (tasks.length < needed) return { proposed: false, reason: 'no task can run beside another' }
+  const { extraAgents, tokens } = estimateTokens(input, tasks.length)
+  if (tokens >= input.thresholdTokens)
+    return {
+      proposed: false,
+      reason: `~${kilo(tokens)} tokens for ${extraAgents} extra agents is not below the ${kilo(input.thresholdTokens)} limit`,
+    }
+  return {
+    proposed: true,
+    tasks,
+    waiting: input.open.length,
+    extraAgents,
+    estimateTokens: tokens,
+    reason: `${tasks.length} of ${input.open.length} waiting tasks name disjoint paths that the running work does not touch; ~${kilo(tokens)} tokens for ${extraAgents} extra ${extraAgents === 1 ? 'agent' : 'agents'}`,
+  }
+}
+
+const FNV_OFFSET = 0x811c9dc5
+const FNV_PRIME = 0x01000193
+
+const hash = (text: string): string => {
+  let value = FNV_OFFSET
+  for (const character of text) {
+    value = Math.imul(value ^ (character.codePointAt(0) ?? 0), FNV_PRIME) >>> 0
+  }
+  return value.toString(16).padStart(8, '0')
+}
+
+/**
+ * A stable fingerprint of what decides a proposal: ticks, active tasks and open tasks, order-independent. Files an
+ * agent touches are left out, they move on every keystroke and would repeat the report.
+ */
+export const taskParallelFingerprint = (input: TaskParallelInput): string =>
+  hash(
+    JSON.stringify([
+      input.lane,
+      input.doneCount,
+      input.active.map((work) => `${work.phase ?? ''}|${work.taskText ?? ''}`).sort(),
+      input.open.map((task) => `${task.phase}|${task.text}`).sort(),
+    ]),
+  )
+
+/**
+ * The proposal to report this heartbeat, if any: only when the fingerprint moved since `previous`, and only a real
+ * proposal. The returned fingerprint is what the caller keeps for the next heartbeat, proposal or not.
+ */
+export const taskParallelReport = (
+  previous: string | undefined,
+  input: TaskParallelInput,
+): { fingerprint: string; proposal: TaskParallelProposal | null } => {
+  const fingerprint = taskParallelFingerprint(input)
+  if (fingerprint === previous) return { fingerprint, proposal: null }
+  const result = proposeTaskParallel(input)
+  return { fingerprint, proposal: result.proposed ? result : null }
+}
+
+const CHECKBOX = /^\s*(?:[-*]\s*)?\[[ xX]\]\s*/
+
+const proposalTaskText = (text: string): string =>
+  ellipsize(terminalSafe(text.replace(/\s+/g, ' ')).replace(CHECKBOX, '').replaceAll('"', "'").trim(), TEXT_LIMIT)
+
+/** `parallel tasks <lane>: "<a>" ∥ "<b>" · ~<n>k tokens for 1 extra agent`, one line. */
+export const formatTaskParallelLine = (lane: string, proposal: TaskParallelProposal): string => {
+  const tasks = proposal.tasks.map((task) => `"${proposalTaskText(task.text)}"`).join(' ∥ ')
+  const agents = proposal.extraAgents === 1 ? 'agent' : 'agents'
+  return `parallel tasks ${proposalTaskText(lane)}: ${tasks} · ~${kilo(proposal.estimateTokens)} tokens for ${proposal.extraAgents} extra ${agents}`
+}

package/src/watch/waiting-line.ts

@@ -0,0 +1,19 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+import type { WaitingItem } from '../plan-format/waiting'
+import { shownWithMore } from '../plans/shown-with-more'
+
+const SHOWN_ITEMS = 3
+const ITEM_LENGTH = 40
+
+const itemText = ({ item }: WaitingItem): string => ellipsize(terminalSafe(item).replace(/\s+/g, ' '), ITEM_LENGTH)
+
+/**
+ * The line that brings back what waits on the user's answer, in every heartbeat and status until the item is closed:
+ * `for you (<n>): <item>; …`, three items and `+<n>` for the rest. Null when no item is open.
+ */
+export const waitingLine = (items: readonly WaitingItem[]): string | null => {
+  const open = items.filter(({ open: isOpen }) => isOpen)
+  if (open.length === 0) return null
+  const { shown, more } = shownWithMore(open, SHOWN_ITEMS)
+  return `for you (${open.length}): ${[...shown.map(itemText), ...(more > 0 ? [`+${more}`] : [])].join('; ')}`
+}

package/src/watch/watch-events.ts

@@ -1,4 +1,5 @@
 import { CHECKS, type ChecksState } from '../plans/pull-requests'
+import { isRecord } from '../shared/is-record'
 import {
   APPOINTMENT_EVENT,
   type AppointmentEvent,
@@ -10,7 +11,6 @@ import { APPROVAL_EVENT, type ApprovalEvent } from './approvals'
 import { type CoordinatorLevel, type CoordinatorReading, isContextLevel, levelStep } from './coordinator-fill'
 import { emptyFailureState, type FailureState, failedTestsOf, isFailureState } from './failures'
 import { emptyFeedbackState, FEEDBACK_EVENT, type FeedbackEvent, type FeedbackState, isFeedbackState } from './feedback'
-import { isRecord } from './json-guards'
 import { isLaneLevels, LANE_FILL_EVENT, type LaneFillEvent, type LaneLevels } from './lane-fill'
 import { isLaneModels, LANE_MODEL_EVENT, type LaneModelEvent, type LaneModels } from './lane-model'
 import { isLaneParallels, LANE_PARALLEL_EVENT, type LaneParallelEvent, type LaneParallels } from './lane-parallel'
@@ -18,6 +18,12 @@ import { type LaneSnapshot, type SeenSeqs, seenSeqsOf } from './lane-watch'
 import { emptyPreviewState, isPreviewState, PREVIEW_EVENT, type PreviewEvent, type PreviewState } from './previews'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { emptySourceState, isSourceState, SOURCE_EVENT, type SourceEvent, type SourceState } from './sources'
+import {
+  isTaskParallelFingerprints,
+  TASK_PARALLEL_EVENT,
+  type TaskParallelEvent,
+  type TaskParallelFingerprints,
+} from './task-parallel'
 import { RUN_EVENT, RUN_STATUS, type WorkflowRun } from './workflow-runs'
 
 /** What the coordinator is told besides a lane that stopped. The values are the words of the report. */
@@ -34,6 +40,7 @@ export const WATCH_EVENT = {
   laneFill: LANE_FILL_EVENT,
   laneModel: LANE_MODEL_EVENT,
   laneParallel: LANE_PARALLEL_EVENT,
+  taskParallel: TASK_PARALLEL_EVENT,
   approval: APPROVAL_EVENT,
   source: SOURCE_EVENT,
   due: APPOINTMENT_EVENT.due,
@@ -86,6 +93,8 @@ export type WatchState = {
   laneModels: LaneModels
   /** The phases last reported as able to run together for each watched lane; a lane without two has none. */
   laneParallels: LaneParallels
+  /** The fingerprint of the parallel-task situation of each watched lane at the last heartbeat; a proposal is made only when it moved. */
+  taskParallels: TaskParallelFingerprints
   /** The ids of the approval requests on disk when they were last read, each reported once while it is open. */
   approvals: string[]
   /** Per configured source of `watch.sources`: the entries seen (`[id, fingerprint]`) and the start of a failure streak. */
@@ -139,6 +148,7 @@ export type WatchEvent =
   | LaneFillEvent
   | LaneModelEvent
   | LaneParallelEvent
+  | TaskParallelEvent
   | ApprovalEvent
   | SourceEvent
   | AppointmentEvent
@@ -173,6 +183,7 @@ export const emptyWatchState = (): WatchState => ({
   laneLevels: {},
   laneModels: {},
   laneParallels: {},
+  taskParallels: {},
   approvals: [],
   sources: emptySourceState(),
   reportMtimes: {},
@@ -218,6 +229,7 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   isLaneLevels(value.laneLevels) &&
   isLaneModels(value.laneModels) &&
   isLaneParallels(value.laneParallels) &&
+  isTaskParallelFingerprints(value.taskParallels) &&
   Array.isArray(value.approvals) &&
   value.approvals.every((id) => typeof id === 'string') &&
   isSourceState(value.sources) &&

package/src/watch/workflow-runs.ts

@@ -1,7 +1,8 @@
 import type { JackherdConfig } from '../config'
 import { GITHUB_HOST } from '../plans/github'
 import { runIdOfLink } from '../plans/pull-requests'
-import { isRecord, parseArray } from './json-guards'
+import { isRecord } from '../shared/is-record'
+import { parseArray } from './json-guards'
 
 /** Which workflow's runs are deploys, and which environments count as their target (`watch.deploy`). */
 export type DeployConfig = NonNullable<JackherdConfig['watch']['deploy']>