dsh-tower 2.0.3 → 2.1.0-beta.1

package/domain/collab/batch.js

@@ -0,0 +1,112 @@
+// Pure batch lifecycle decisions and status projection.
+//
+// `domain/batch.js` owns the admission/close evidence validation; this module
+// owns the id assignment, close/abandon record transitions, and status payload
+// that app/batch.js used to keep inline. Receipt file reads stay in the tool
+// layer.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { summarize } from '../batch.js'
+
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'batch-invalid') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * Next free `B<n>` id.
+ * @param {any[]} batches
+ * @returns {string}
+ */
+export function nextBatchId(batches) {
+  const max = batches.reduce((value, batch) => {
+    const match = /^B(\d+)$/.exec(String(batch.id ?? ''))
+    return match ? Math.max(value, Number(match[1])) : value
+  }, 0)
+  return `B${max + 1}`
+}
+
+/**
+ * Project the persisted batch record from normalized create input.
+ * @param {string} id
+ * @param {any} normalized
+ * @param {string} actor
+ * @param {number} now
+ * @returns {any}
+ */
+export function createBatchRecord(id, normalized, actor, now) {
+  return {
+    id,
+    status: 'open',
+    ...normalized,
+    createdBy: actor,
+    createdAt: now,
+  }
+}
+
+/**
+ * Mark a validated open batch closed with its evidence snapshot.
+ * @param {any} batch
+ * @param {{ checks?: unknown, treeTip?: unknown, receiptHashes?: unknown }} options
+ * @param {string} actor
+ * @param {number} now
+ * @returns {any}
+ */
+export function closeBatchRecord(batch, options, actor, now) {
+  batch.status = 'closed'
+  batch.closedAt = now
+  batch.closedBy = actor
+  batch.close = {
+    checks: options.checks ?? [],
+    treeTip: options.treeTip ?? null,
+    receiptHashes: options.receiptHashes ?? {},
+    at: now,
+  }
+  return batch
+}
+
+/**
+ * A closed batch cannot be abandoned; an already-abandoned one is a no-op.
+ * @param {any} batch
+ * @param {string} batchId
+ * @returns {{ alreadyAbandoned: boolean }}
+ */
+export function abandonBatchCheck(batch, batchId) {
+  if (batch.status === 'closed') fail(`batch ${batchId} is already closed`)
+  return { alreadyAbandoned: batch.status === 'abandoned' }
+}
+
+/**
+ * Apply an abandonment to the draft batch.
+ * @param {{ batch: any, actor: string, reason?: unknown, now: number }} params
+ * @returns {any}
+ */
+export function applyBatchAbandon({ batch, actor, reason, now }) {
+  batch.status = 'abandoned'
+  batch.abandonedAt = now
+  batch.abandonedBy = actor
+  batch.abandonReason = typeof reason === 'string' && reason.trim() ? reason.trim() : null
+  return batch
+}
+
+/**
+ * Read-only `tower_batch status` payload.
+ * @param {TowerState} state
+ * @param {string | undefined} batchId
+ * @returns {any}
+ */
+export function batchStatusPayload(state, batchId) {
+  const batches = state.batches ?? []
+  const batch = batchId ? batches.find((entry) => entry.id === batchId) : null
+  if (batchId && !batch) fail(`unknown batch "${batchId}"`)
+  return {
+    batches: batches.map((entry) => summarize(state, entry)),
+    ...(batch ? { batch: summarize(state, batch) } : {}),
+  }
+}

package/domain/collab/messages.js

@@ -0,0 +1,127 @@
+// Pure message routing, read tracking, and inbox projections.
+//
+// app/messages.js owns the state lock, load, persistence, and activity log;
+// app/roster.js's unreadFor delegates to `unreadMessages` here.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('invalid-argument', message)
+}
+
+/**
+ * Validate the recipient against the roster plus the synthetic `tower` name.
+ * @param {{ roster?: RosterEntry[], to: string, from: string }} params
+ * @returns {void}
+ */
+export function assertMessageRecipient({ roster = [], to, from }) {
+  const names = new Set(roster.map((entry) => entry.name))
+  names.add('tower')
+  if (to !== 'all' && !names.has(to)) {
+    fail(`unknown message recipient "${to}" (known: ${[...names].join(', ')}, all)`)
+  }
+  if (to === from) fail('refusing to send a message to yourself')
+}
+
+/**
+ * Project the persisted message record.
+ * @param {any} input
+ * @param {number} seq
+ * @param {number} now
+ * @returns {any}
+ */
+export function createMessage(input, seq, now) {
+  return {
+    id: `msg-${seq}`,
+    seq,
+    from: input.from,
+    to: input.to,
+    subject: input.subject,
+    body: input.body,
+    scope: input.scope ?? null,
+    consentRef: input.consentRef ?? null,
+    at: now,
+    readBy: [],
+    delivery: [],
+  }
+}
+
+/**
+ * Append delivery results to a message, preserving earlier entries.
+ * @param {{ delivery?: unknown[] }} message
+ * @param {unknown[]} results
+ * @returns {unknown[]}
+ */
+export function addDelivery(message, results) {
+  message.delivery = [...(message.delivery ?? []), ...results]
+  return message.delivery
+}
+
+/**
+ * Inbox page plus read-marking mutation. Returns `changed` so the use case can
+ * decide whether the state file needs a write.
+ * @param {any[]} messages
+ * @param {{ reader: string, limit?: number, includeRead?: boolean }} input
+ * @param {number} now
+ * @returns {{ payload: any, changed: boolean }}
+ */
+export function inboxView(messages, input, now) {
+  const reader = input.reader
+  const limit = Math.max(1, Math.min(100, input.limit ?? 20))
+  const includeRead = input.includeRead === true
+  const visible = [...messages]
+    .reverse()
+    .filter((message) => (message.to === reader || message.to === 'all') && message.from !== reader)
+  const unread = visible.filter((message) => !(message.readBy ?? []).includes(reader))
+  const page = (includeRead ? visible : unread).slice(0, limit)
+
+  let changed = false
+  for (const message of page) {
+    if (!(message.readBy ?? []).includes(reader)) {
+      message.readBy = [...(message.readBy ?? []), reader]
+      message.readAt = { ...(message.readAt ?? {}), [reader]: now }
+      changed = true
+    }
+  }
+  const unreadRemaining = visible.filter((message) => !(message.readBy ?? []).includes(reader)).length
+  return {
+    payload: {
+      reader,
+      messages: page.map((message) => ({
+        id: message.id,
+        from: message.from,
+        to: message.to,
+        subject: message.subject,
+        body: message.body,
+        scope: message.scope ?? null,
+        at: message.at,
+        delivery: message.delivery ?? [],
+        ackAt: message.readAt?.[reader] ?? null,
+      })),
+      pageSize: page.length,
+      unreadRemaining,
+    },
+    changed,
+  }
+}
+
+/**
+ * Unread inbox rows for one recipient (messages from self never count).
+ * @param {TowerState} state
+ * @param {string} name
+ * @returns {any[]}
+ */
+export function unreadMessages(state, name) {
+  return (state.messages ?? []).filter((message) => {
+    if (message.from === name) return false
+    if (message.to !== name && message.to !== 'all') return false
+    return !(/** @type {any[]} */ (message.readBy ?? [])).includes(name)
+  })
+}

package/domain/collab/roster.js

@@ -0,0 +1,158 @@
+// Pure roster observation and stale/inactive policy.
+//
+// app/roster.js owns the state lock, load, persistence, and activity log; the
+// transitions below mutate only the in-memory roster rows they are given.
+// @ts-check
+import { ROSTER_INACTIVE } from '../roster.js'
+
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+
+/**
+ * @param {RosterEntry} entry
+ * @returns {void}
+ */
+export function clearStale(entry) {
+  delete entry.stale
+  delete entry.staleAt
+}
+
+/**
+ * Count repeated absence observations and list rows ready to adopt.
+ * @param {RosterEntry[]} roster
+ * @param {{ present?: unknown[], absent?: unknown[], confirmations?: unknown }} observations
+ * @param {number} now
+ * @returns {{ candidates: string[], changed: boolean }}
+ */
+export function recordRosterObservations(roster, { present = [], absent = [], confirmations = 2 }, now) {
+  const presentIds = new Set(present)
+  const absentIds = new Set(absent)
+  /** @type {string[]} */
+  const candidates = []
+  let changed = false
+  for (const entry of roster) {
+    if (presentIds.has(entry.agentId)) {
+      if (entry.absentObservations !== undefined) {
+        delete entry.absentObservations
+        delete entry.absentSince
+        changed = true
+      }
+      continue
+    }
+    if (!absentIds.has(entry.agentId)) continue
+    entry.absentObservations = (/** @type {number} */ (entry.absentObservations ?? 0)) + 1
+    entry.absentSince ??= now
+    changed = true
+    const observations = /** @type {number} */ (entry.absentObservations)
+    if (observations >= Math.max(2, Number(confirmations) || 2)) {
+      candidates.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { candidates, changed }
+}
+
+/**
+ * Release live slots whose catalog activity is explicitly inactive.
+ * @param {RosterEntry[]} roster
+ * @param {Record<string, string>} activity
+ * @param {number} now
+ * @returns {{ released: string[] }}
+ */
+export function reconcileObservedInactive(roster, activity = {}, now) {
+  /** @type {string[]} */
+  const released = []
+  for (const entry of roster) {
+    if (entry.state === 'reserved' || ROSTER_INACTIVE.has(entry.state)) continue
+    const agentId = /** @type {string} */ (entry.agentId)
+    if (activity[agentId] !== 'inactive') continue
+    entry.state = 'inactive'
+    entry.outcome = 'catalog reported inactive'
+    entry.outcomeAt = now
+    clearStale(entry)
+    released.push(entry.name)
+  }
+  return { released }
+}
+
+/**
+ * Retire entries by agent id, skipping rows already retired.
+ * @param {RosterEntry[]} roster
+ * @param {unknown[]} agentIds
+ * @param {number} now
+ * @returns {{ retired: string[] }}
+ */
+export function retireEntries(roster, agentIds, now) {
+  if (!Array.isArray(agentIds) || agentIds.length === 0) return { retired: [] }
+  /** @type {string[]} */
+  const retired = []
+  for (const entry of roster) {
+    if (entry.state !== 'retired' && agentIds.includes(entry.agentId)) {
+      entry.state = 'retired'
+      entry.retiredAt = now
+      clearStale(entry)
+      retired.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { retired }
+}
+
+/**
+ * Mark entries missing unless they are already inactive.
+ * @param {RosterEntry[]} roster
+ * @param {unknown[]} agentIds
+ * @param {number} now
+ * @returns {{ missing: string[] }}
+ */
+export function markMissingEntries(roster, agentIds, now) {
+  if (!Array.isArray(agentIds) || agentIds.length === 0) return { missing: [] }
+  /** @type {string[]} */
+  const missing = []
+  for (const entry of roster) {
+    if (!ROSTER_INACTIVE.has(entry.state) && agentIds.includes(entry.agentId)) {
+      entry.state = 'missing'
+      entry.missingSince = now
+      clearStale(entry)
+      missing.push(/** @type {string} */ (entry.agentId))
+    }
+  }
+  return { missing }
+}
+
+/**
+ * Watchdog sweep: catalog-inactive rows become inactive; rows absent from an
+ * authoritative catalog and older than `staleMs` become stale. Unknown catalog
+ * state is never treated as stopped.
+ * @param {RosterEntry[]} roster
+ * @param {{ activity?: Record<string, string>, staleMs?: unknown, authoritative?: unknown }} input
+ * @param {number} now
+ * @returns {{ marked: string[], idled: string[] }}
+ */
+export function sweepRosterState(roster, input = {}, now) {
+  const staleMs = Number(input.staleMs) || 0
+  if (staleMs <= 0 || input.authoritative !== true) return { marked: [], idled: [] }
+  const activity = input.activity ?? {}
+  /** @type {string[]} */
+  const marked = []
+  /** @type {string[]} */
+  const idled = []
+  for (const entry of roster) {
+    if (ROSTER_INACTIVE.has(entry.state)) continue
+    const observed = activity[/** @type {string} */ (entry.agentId)]
+    if (observed === 'inactive') {
+      entry.state = 'inactive'
+      entry.outcome = entry.outcome ?? 'idle (catalog)'
+      entry.outcomeAt = now
+      idled.push(entry.name)
+      continue
+    }
+    if (observed === 'running') continue
+    if (observed !== undefined) continue
+    const age = now - Number(entry.spawnedAt ?? now)
+    if (age > staleMs) {
+      entry.state = 'stale'
+      entry.stale = true
+      entry.staleAt = now
+      marked.push(entry.name)
+    }
+  }
+  return { marked, idled }
+}

package/domain/collab/spawn.js

@@ -0,0 +1,188 @@
+// Pure spawn reservation/outcome policy: roster entry projections, role and
+// live-worker limit decisions.
+//
+// app/spawn.js owns the state lock, load, Git spawn-tip capture, persistence,
+// and activity log. Preset/provider selection happens in tools/spawn.js and is
+// intentionally not duplicated here.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { ROSTER_INACTIVE, countLiveWorkers, workerEntries } from '../roster.js'
+import { clearStale } from './roster.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+
+/**
+ * @param {string} message
+ * @returns {never}
+ */
+function fail(message) {
+  throw new TowerToolError('invalid-argument', message)
+}
+
+/**
+ * @param {unknown} role
+ * @returns {boolean}
+ */
+export function isWorkerRole(role) {
+  return role === 'worker'
+}
+
+/**
+ * The configured live-worker ceiling, defaulting to four.
+ * @param {unknown} maxLiveWorkers
+ * @returns {number}
+ */
+export function liveWorkerLimit(maxLiveWorkers) {
+  return Number(maxLiveWorkers) || 4
+}
+
+/**
+ * Record that a spawned agent failed or went idle.
+ * @param {RosterEntry} entry
+ * @param {{ state?: string, detail?: unknown }} input
+ * @param {number} now
+ * @returns {RosterEntry}
+ */
+export function applySpawnOutcome(entry, input, now) {
+  entry.state = input.state ?? 'failed'
+  entry.outcome = input.detail ? String(input.detail).slice(0, 1000) : null
+  entry.outcomeAt = now
+  clearStale(entry)
+  return entry
+}
+
+/**
+ * Record that a live agent was interrupted by the tower.
+ * @param {RosterEntry} entry
+ * @param {{ reason?: unknown }} input
+ * @param {number} now
+ * @returns {RosterEntry}
+ */
+export function applyInterrupt(entry, input, now) {
+  entry.state = 'interrupted'
+  entry.outcome = String(input.reason ?? 'interrupted by tower').slice(0, 1000)
+  entry.outcomeAt = now
+  clearStale(entry)
+  return entry
+}
+
+/**
+ * A reserved roster row: the name is claimed before activation so a failed
+ * spawn remains recoverable.
+ * @param {any} input
+ * @param {number} now
+ * @returns {RosterEntry}
+ */
+export function reservedRosterEntry(input, now) {
+  return {
+    name: input.name,
+    role: input.role,
+    agentId: null,
+    sessionId: null,
+    parentSessionId: input.parentSessionId,
+    missionId: input.missionId,
+    cwd: input.cwd ?? null,
+    branch: input.branch ?? null,
+    spawnTip: null,
+    state: 'reserved',
+    reservedAt: now,
+    spawnedAt: now,
+  }
+}
+
+/**
+ * Validate a reservation request and project its row.
+ * @param {{ roster: RosterEntry[], input: any, now: number }} params
+ * @returns {RosterEntry}
+ */
+export function reserveRosterEntry({ roster, input, now }) {
+  if (roster.some((entry) => entry.name === input.name)) fail(`roster name already used: ${input.name}`)
+  return reservedRosterEntry(input, now)
+}
+
+/**
+ * Validate and apply a spawn record. Mutates the roster (retiring prior worker
+ * rows and inserting/reusing the entry) and the mission owner/status/gen.
+ * @param {{ roster: RosterEntry[], mission: Mission, input: any, spawnTip: string | null, maxLiveWorkers: unknown, now: number }} params
+ * @returns {RosterEntry}
+ */
+export function recordSpawnEntry({ roster, mission, input, spawnTip, maxLiveWorkers, now }) {
+  const reserved = roster.find((entry) => entry.name === input.name && entry.state === 'reserved' && !entry.agentId)
+  if (!reserved && roster.some((entry) => entry.name === input.name)) {
+    fail(`roster name already used: ${input.name}`)
+  }
+  if (roster.some((entry) => entry.agentId && entry.agentId === input.agentId)) {
+    fail(`agent ${input.agentId} is already in the roster`)
+  }
+  /** @type {RosterEntry} */
+  const entry = {
+    name: input.name,
+    role: input.role,
+    agentId: input.agentId,
+    sessionId: input.sessionId ?? input.agentId,
+    parentSessionId: input.parentSessionId,
+    missionId: input.missionId,
+    cwd: input.cwd ?? null,
+    branch: input.branch ?? null,
+    spawnTip,
+    state: 'active',
+    spawnedAt: now,
+  }
+  if (isWorkerRole(input.role)) {
+    const snapshot = /** @type {any} */ ({ roster })
+    const previous = workerEntries(snapshot, mission.id)
+    const live = previous.find((row) => !ROSTER_INACTIVE.has(row.state) && row.state !== 'reserved')
+    if (live && !input.takeover) {
+      fail(
+        `mission ${mission.id} already has a live worker "${live.name}"; stop it with tower_interrupt, or pass takeover:true after it is no longer running`,
+      )
+    }
+    // A new owner always retires the mission's older worker entries, including
+    // idle `inactive` ones; otherwise the next spawn would see several entries
+    // for the same mission and the old idle worker would block forever.
+    for (const old of previous) {
+      if (old.state === 'retired' || old.state === 'reserved') continue
+      old.state = 'retired'
+      old.outcome = `replaced by ${input.name}${input.takeover ? ' (takeover)' : ''}`
+      old.outcomeAt = now
+      clearStale(old)
+    }
+    const max = liveWorkerLimit(maxLiveWorkers)
+    if (countLiveWorkers(snapshot) >= max) {
+      fail(`live worker limit reached (${max}); stop a worker or raise spawn.maxLiveWorkers`)
+    }
+    const generation = (mission.ownerGeneration ?? 0) + 1
+    entry.generation = generation
+    mission.ownerGeneration = generation
+    mission.owner = input.name
+    if (mission.status === 'planned') mission.status = 'active'
+  }
+  if (reserved) Object.assign(reserved, entry)
+  else roster.push(entry)
+  return reserved ?? entry
+}
+
+/**
+ * Pure read projection for `tower_roster`.
+ * @param {import('../../types/index.js').TowerState} state
+ * @returns {any}
+ */
+export function rosterProjection(state) {
+  return {
+    revision: state.revision,
+    roster: (state.roster ?? []).map((entry) => ({ ...entry })),
+    missions: state.missions.map((mission) => ({
+      id: mission.id,
+      status: mission.status,
+      owner: mission.owner ?? null,
+      worktree: mission.worktree
+        ? {
+            path: mission.worktree.path,
+            branch: mission.worktree.branch,
+            baseCommit: mission.worktree.baseCommit,
+          }
+        : null,
+    })),
+  }
+}