dsh-tower 2.0.4 → 2.1.0

package/domain/missions/completion.js

@@ -0,0 +1,167 @@
+// Pure worker-completion policy and check normalization.
+//
+// app/checkCompletion.js still loads state, verifies the worktree/commits with
+// Git, and persists the transition; the rules below are repository-free.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').RosterEntry} RosterEntry */
+
+/**
+ * Hard cap for `tower_complete.report`, in UTF-8 bytes (32 KiB). The value is
+ * the default of `gates.maxReportBytes`; a repository may lower or raise it.
+ */
+export const DEFAULT_MAX_REPORT_BYTES = 32 * 1024
+
+/**
+ * UTF-8 byte length, so multi-byte text is not silently favoured by a
+ * character-count bound.
+ * @param {string} value
+ * @returns {number}
+ */
+export function utf8ByteLength(value) {
+  return Buffer.byteLength(String(value), 'utf8')
+}
+
+/**
+ * Reject a report over the cap instead of truncating it: a silent cut loses
+ * evidence and cannot be recovered by the tower. The writer is told to keep the
+ * full text beside the branch and reference it.
+ * @param {string} report
+ * @param {number} [maxBytes]
+ * @returns {number} accepted UTF-8 byte length
+ */
+export function assertReportSize(report, maxBytes = DEFAULT_MAX_REPORT_BYTES) {
+  const bytes = utf8ByteLength(report)
+  if (bytes > maxBytes) {
+    throw new TowerToolError(
+      'invalid-argument',
+      `report is ${bytes} bytes (UTF-8), over the ${maxBytes}-byte cap; reports are rejected, not truncated — write the full text to a file in the mission worktree and reference the path in the report`,
+      {
+        nextAction: 'write the full text to a file in the mission worktree and reference the path in the report',
+      },
+    )
+  }
+  return bytes
+}
+
+/**
+ * Byte size of a stored completion report. Older documents have no
+ * `reportBytes`, so the body is measured on read; the field is never required.
+ * @param {any} completionReport
+ * @returns {number | null}
+ */
+export function completionReportBytes(completionReport) {
+  if (!isPlainObject(completionReport)) return null
+  const stored = completionReport.reportBytes
+  if (Number.isInteger(stored) && stored >= 0) return stored
+  return typeof completionReport.report === 'string' ? utf8ByteLength(completionReport.report) : null
+}
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Normalize `tower_complete` check evidence.
+ * @param {any} checks
+ * @returns {any[]}
+ */
+export function normalizeChecks(checks) {
+  if (checks === undefined) return []
+  if (!Array.isArray(checks)) fail('checks must be an array')
+  if (checks.length > 20) fail('checks may contain at most 20 entries')
+  return checks.map((check, index) => {
+    if (!isPlainObject(check)) fail(`checks[${index}] must be an object`)
+    const name = typeof check.name === 'string' ? check.name.trim() : ''
+    if (!name) fail(`checks[${index}].name must be a non-empty string`)
+    /** @type {Record<string, any>} */
+    const entry = { name }
+    if (typeof check.command === 'string' && check.command.trim()) entry.command = check.command.trim()
+    if (check.exitCode !== undefined && check.exitCode !== null) {
+      if (!Number.isInteger(check.exitCode)) fail(`checks[${index}].exitCode must be an integer`)
+      entry.exitCode = check.exitCode
+    }
+    if (typeof check.evidence === 'string' && check.evidence.trim()) entry.evidence = check.evidence.trim().slice(0, 4000)
+    return entry
+  })
+}
+
+/**
+ * Resolve and validate the reporting worker and the mission's completion
+ * preconditions that need no repository access.
+ * @param {{ mission: Mission, roster: RosterEntry[] | undefined, input: any, maxReportBytes?: number }} params
+ * @returns {RosterEntry}
+ */
+export function assertCompletionRequest({ mission, roster, input, maxReportBytes }) {
+  const worker = (roster ?? []).find((entry) => entry.agentId === input.agentId)
+  if (!worker || worker.missionId !== mission.id) {
+    fail(`agent ${input.agentId} is not assigned to mission ${mission.id}`)
+  }
+  if (worker.role !== 'worker') fail(`agent ${worker.name} is a ${worker.role}, not a worker`)
+  if (['retired', 'failed', 'interrupted', 'missing', 'stale'].includes(worker.state)) {
+    fail(`agent ${worker.name} is ${worker.state}; a stopped worker cannot report completion`)
+  }
+  if (mission.owner && mission.owner !== worker.name) {
+    fail(`agent ${worker.name} is not the current owner of mission ${mission.id} (owner: ${mission.owner})`)
+  }
+  if (mission.status === 'completed') fail(`mission ${mission.id} is already completed`)
+  if (!['active', 'planned'].includes(mission.status)) {
+    fail(`mission ${mission.id} is ${mission.status}; it cannot be completed from that state`)
+  }
+  if (typeof input.report !== 'string' || input.report.trim().length === 0) {
+    fail('tower_complete requires a non-empty report')
+  }
+  assertReportSize(input.report.trim(), maxReportBytes)
+  const openTasks = (mission.tasks ?? []).filter((task) => task.status === 'open')
+  if (openTasks.length > 0) {
+    fail(
+      `mission ${mission.id} still has ${openTasks.length} open task(s): ${openTasks
+        .map((task) => task.text)
+        .join('; ')}`,
+    )
+  }
+  const blockers = mission.blockers ?? []
+  if (blockers.length > 0) {
+    fail(`mission ${mission.id} has unresolved blockers: ${blockers.join('; ')}`)
+  }
+  if (!mission.worktree) fail(`mission ${mission.id} has no worktree`)
+  return worker
+}
+
+/**
+ * Unread inbox messages block completion.
+ * @param {{ mission: Mission, worker: RosterEntry, unread: unknown[] }} params
+ * @returns {void}
+ */
+export function assertCompletionInbox({ mission, worker, unread }) {
+  if (unread.length > 0) {
+    fail(
+      `mission ${mission.id} cannot complete with ${unread.length} unread inbox message(s) for ${worker.name}; call tower_inbox until unread is 0, incorporate them, then retry`,
+    )
+  }
+}
+
+/**
+ * Project the completion report stored on the mission.
+ * @param {{ report: string, worker: RosterEntry, checks: any[], now: number, maxReportBytes?: number }} params
+ * @returns {any}
+ */
+export function completionReport({ report, worker, checks, now, maxReportBytes }) {
+  const text = report.trim()
+  return { report: text, reportBytes: assertReportSize(text, maxReportBytes), by: worker.name, at: now, checks }
+}

package/domain/missions/findings.js

@@ -0,0 +1,201 @@
+// Pure finding normalization, filtering, and transition policy.
+//
+// app/findings.js owns loading state, the writer lock, sequence assignment,
+// persistence, and the activity entry.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { FINDING_SEVERITIES, FINDING_STATUSES, FINDING_TRANSITIONS, FINDING_TYPES } from '../mission.js'
+import { countFindings, findingSummary } from '../summary.js'
+
+/** @typedef {import('../../types/index.js').Finding} Finding */
+/** @typedef {import('../../types/index.js').Mission} Mission */
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isNonEmpty(value) {
+  return value !== undefined && value !== null && value !== ''
+}
+
+/**
+ * Validate and project the user-supplied fields of a new finding.
+ * @param {any} input
+ * @param {Mission[]} missions
+ * @returns {any}
+ */
+export function normalizeFindingInput(input, missions) {
+  if (!FINDING_TYPES.includes(input.type)) {
+    fail(`finding type must be one of ${FINDING_TYPES.join('|')}`)
+  }
+  const title = String(input.title ?? '').trim()
+  if (!title) fail('finding title is required')
+  const summary = String(input.summary ?? '').trim()
+  if (!summary) fail('finding summary is required')
+  const details = String(input.details ?? '').trim()
+  if (!details) fail('finding details are required')
+  const suggestedFix = String(input.suggested_fix ?? '').trim()
+  if (!suggestedFix) fail('finding suggested_fix is required')
+  const severity = input.severity ?? null
+  if (severity !== null && !FINDING_SEVERITIES.includes(severity)) {
+    fail(`finding severity must be one of ${FINDING_SEVERITIES.join('|')}`)
+  }
+  let mission = null
+  if (isNonEmpty(input.missionId)) {
+    mission = missions.find((entry) => entry.id === input.missionId) ?? null
+    if (!mission) fail(`unknown mission "${input.missionId}"`, 'mission-not-found')
+  }
+  return {
+    type: input.type,
+    title,
+    severity,
+    summary,
+    location: typeof input.location === 'string' && input.location.trim() ? input.location.trim() : null,
+    details,
+    suggested_fix: suggestedFix,
+    missionId: mission ? mission.id : null,
+    branch: mission && mission.worktree ? mission.worktree.branch : null,
+  }
+}
+
+/**
+ * Project the complete finding record that gets persisted.
+ * @param {any} fields
+ * @param {{ seq: number, now: number, reportedBy: unknown }} params
+ * @returns {Finding}
+ */
+export function newFinding(fields, { seq, now, reportedBy }) {
+  return {
+    id: `F${seq}`,
+    seq,
+    ...fields,
+    reportedBy,
+    at: now,
+    status: 'open',
+  }
+}
+
+/**
+ * @param {any} actor
+ * @returns {{ name: string, role: string }}
+ */
+export function normalizeFindingActor(actor) {
+  const resolved = actor ?? { name: 'tower', role: 'tower' }
+  if (typeof resolved.role !== 'string') fail('finding actor role must be a string')
+  return resolved
+}
+
+/**
+ * @param {any} input
+ * @returns {boolean}
+ */
+export function wantsFindingUpdate(input) {
+  const hasId = isNonEmpty(input.id)
+  return hasId && (input.status !== undefined || input.note !== undefined)
+}
+
+/**
+ * Pure read/list projection. Throws on an unknown id or an invalid filter.
+ * @param {Finding[]} findings
+ * @param {any} input
+ * @returns {any}
+ */
+export function readFindingsView(findings, input) {
+  const counts = countFindings(findings)
+  if (isNonEmpty(input.id)) {
+    const finding = findings.find((entry) => entry.id === input.id)
+    if (!finding) fail(`unknown finding "${input.id}"`, 'finding-not-found')
+    return { finding: { ...finding }, counts, total: findings.length, filtered: 1, action: 'read' }
+  }
+  if (input.status !== undefined && input.status !== 'all') {
+    if (!FINDING_STATUSES.includes(input.status)) {
+      fail(`finding status must be one of ${FINDING_STATUSES.join('|')}`)
+    }
+  }
+  let visible = findings
+  if (input.status !== undefined && input.status !== 'all') {
+    visible = visible.filter((finding) => (finding.status ?? 'open') === input.status)
+  }
+  if (input.type !== undefined) {
+    if (!FINDING_TYPES.includes(input.type)) fail(`finding type must be one of ${FINDING_TYPES.join('|')}`)
+    visible = visible.filter((finding) => finding.type === input.type)
+  }
+  if (input.severity !== undefined) {
+    if (!FINDING_SEVERITIES.includes(input.severity)) {
+      fail(`finding severity must be one of ${FINDING_SEVERITIES.join('|')}`)
+    }
+    visible = visible.filter((finding) => finding.severity === input.severity)
+  }
+  if (isNonEmpty(input.missionId)) {
+    visible = visible.filter((finding) => finding.missionId === input.missionId)
+  }
+  if (input.open === true) {
+    visible = visible.filter((finding) => !['fixed', 'wontfix'].includes(finding.status ?? 'open'))
+  }
+  const limit = Math.max(1, Math.min(200, Number.isInteger(input.limit) ? input.limit : 50))
+  const page = visible.slice(-limit).reverse()
+  return {
+    findings: page.map((finding) => findingSummary(finding)),
+    counts,
+    total: findings.length,
+    filtered: visible.length,
+    action: 'list',
+  }
+}
+
+/**
+ * Apply one finding lifecycle transition to the draft finding.
+ * @param {{ finding: Finding, input: any, actor: { name: string, role: string }, now: number }} params
+ * @returns {{ noteAdded: boolean }}
+ */
+export function applyFindingUpdate({ finding, input, actor, now }) {
+  if (actor.role === 'reviewer') {
+    fail('reviewers may list and read findings, but only the tower or a worker may change finding status', 'not-authorized')
+  }
+  let noteAdded = false
+  if (input.status !== undefined) {
+    if (input.status === 'all') {
+      fail('finding status "all" is only a list filter; pass a concrete status when updating')
+    }
+    if (!FINDING_STATUSES.includes(input.status)) {
+      fail(`finding status must be one of ${FINDING_STATUSES.join('|')}`)
+    }
+    const current = finding.status ?? 'open'
+    const allowed = FINDING_TRANSITIONS[current] ?? []
+    if (!allowed.includes(input.status)) {
+      fail(`finding ${finding.id} cannot move from ${current} to ${input.status}`, 'invalid-transition')
+    }
+    finding.status = input.status
+    if (input.status === 'fixed' || input.status === 'wontfix') finding.closedAt = now
+    else delete finding.closedAt
+  }
+  if (input.note !== undefined) {
+    if (typeof input.note !== 'string' || input.note.trim().length === 0) {
+      fail('finding note must be a non-empty string')
+    }
+    const record = /** @type {any} */ (finding)
+    if (!Array.isArray(record.notes)) record.notes = []
+    record.notes.push({ by: actor.name, at: now, text: input.note.trim() })
+    noteAdded = true
+  }
+  finding.updatedAt = now
+  return { noteAdded }
+}
+
+/**
+ * @param {Finding} finding
+ * @param {Finding[]} all
+ * @returns {any}
+ */
+export function findingUpdateView(finding, all) {
+  return { finding: { ...finding }, counts: countFindings(all), total: all.length, filtered: 1, action: 'updated' }
+}

package/domain/missions/lifecycle.js

@@ -0,0 +1,186 @@
+// Pure mission lifecycle transition policy.
+//
+// app/mission.js supplies the loaded mission/state and persists the result;
+// this module owns the authorization and transition rules and mutates only the
+// in-memory mission draft it is given.
+// @ts-check
+import { TowerToolError } from '../errors.js'
+import { MISSION_STATUSES, TERMINAL_STATUSES, canTransition, pauseCauseError } from '../mission.js'
+import { normalizeScope, scopesOverlap } from '../scope.js'
+
+/** @typedef {import('../../types/index.js').Mission} Mission */
+/** @typedef {import('../../types/index.js').TowerState} TowerState */
+
+const TERMINAL = TERMINAL_STATUSES
+
+/**
+ * @param {string} message
+ * @param {string} [code]
+ * @returns {never}
+ */
+function fail(message, code = 'invalid-argument') {
+  throw new TowerToolError(code, message)
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function normalizePauseCause(value) {
+  const error = pauseCauseError(/** @type {string | null | undefined} */ (value))
+  if (error) fail(error)
+  return value === undefined || value === null || value === '' ? 'user' : /** @type {string} */ (value)
+}
+
+/**
+ * Reject actor/input combinations a worker may not perform. The tower owns
+ * status, scope, blockers, and pause metadata; a worker only reports work.
+ * @param {Mission} mission
+ * @param {{ name?: string, role?: string }} actor
+ * @param {any} input
+ * @returns {void}
+ */
+export function assertMissionActor(mission, actor, input) {
+  const workerRequest = actor.role === 'worker'
+  if (actor.role === 'reviewer') {
+    fail('only the tower or a worker may update a mission; reviewers submit tower_review', 'not-authorized')
+  }
+  if (workerRequest && mission.owner && mission.owner !== actor.name) {
+    fail(`worker ${actor.name} does not own mission ${mission.id} (owner: ${mission.owner})`, 'not-authorized')
+  }
+  if (workerRequest) {
+    if (input.status !== undefined) {
+      fail('only the tower can change mission status directly; workers report completion with tower_complete', 'not-authorized')
+    }
+    if (input.scope !== undefined) fail('only the tower can change mission scope', 'not-authorized')
+    if (input.clear_blockers === true) fail('only the tower can clear blockers', 'not-authorized')
+    if (input.pause_cause !== undefined || input.authorization !== undefined) {
+      fail('only the tower can record pause/authorization metadata', 'not-authorized')
+    }
+  }
+}
+
+/**
+ * Apply one validated `tower_mission` patch to the mission draft and return
+ * the human-readable change list used by the activity log.
+ * @param {{ mission: Mission, state: TowerState, input: any, config: any }} params
+ * @returns {{ changes: string[] }}
+ */
+export function applyMissionUpdate({ mission, state, input, config }) {
+  const actor = input.actor ?? { name: 'tower', role: 'tower' }
+  assertMissionActor(mission, actor, input)
+  if (input.pause_cause !== undefined && input.status !== 'paused') {
+    fail('pause_cause is only valid together with status "paused"')
+  }
+  if (input.status === 'abandoned' && (typeof input.note !== 'string' || input.note.trim().length === 0)) {
+    fail('abandoning a mission requires a non-empty note (reason)')
+  }
+  /** @type {string[]} */
+  const changes = []
+
+  if (input.status !== undefined) {
+    if (typeof input.status !== 'string' || !MISSION_STATUSES.includes(input.status)) {
+      fail(`unknown mission status "${input.status}"`)
+    }
+    if (input.status === 'merged') {
+      fail('merged is recorded only by tower_merge, not by a generic mission patch', 'invalid-transition')
+    }
+    if (!canTransition(mission.status, input.status)) {
+      fail(`mission ${mission.id} cannot move from ${mission.status} to ${input.status}`, 'invalid-transition')
+    }
+    if (input.status === 'paused') {
+      mission.pauseCause = normalizePauseCause(input.pause_cause)
+    }
+    if (mission.status === 'paused' && input.status === 'active') {
+      const requireAuthorization = config.mode.requireResumeAuthorization === true
+      if (requireAuthorization && (mission.pauseCause ?? 'user') === 'user') {
+        if (typeof input.authorization !== 'string' || input.authorization.trim().length === 0) {
+          fail('resuming a user-paused mission requires a non-empty authorization reference')
+        }
+      }
+      if (typeof input.authorization === 'string' && input.authorization.trim()) {
+        mission.authorizationRef = input.authorization.trim()
+      }
+    }
+    mission.status = input.status
+    changes.push(`status=${input.status}`)
+  }
+
+  if (input.task_done !== undefined) {
+    const needle = String(input.task_done)
+    const tasks = /** @type {any[]} */ (mission.tasks)
+    const task = tasks.find(
+      (entry) => entry.status === 'open' && entry.text.toLowerCase().includes(needle.toLowerCase()),
+    )
+    if (!task) fail(`no open task matching "${needle}" in mission ${mission.id}`)
+    task.status = 'done'
+    changes.push(`task_done="${task.text}"`)
+  }
+
+  if (input.task_drop !== undefined) {
+    if (typeof input.task_drop_reason !== 'string' || input.task_drop_reason.trim().length === 0) {
+      fail('task_drop requires task_drop_reason')
+    }
+    const needle = String(input.task_drop)
+    const tasks = /** @type {any[]} */ (mission.tasks)
+    const task = tasks.find(
+      (entry) => entry.status === 'open' && entry.text.toLowerCase().includes(needle.toLowerCase()),
+    )
+    if (!task) fail(`no open task matching "${needle}" in mission ${mission.id}`)
+    task.status = 'dropped'
+    task.note = input.task_drop_reason.trim()
+    const notes = /** @type {string[]} */ (mission.notes)
+    notes.push(`task dropped: ${task.text} — ${task.note}`)
+    changes.push(`task_drop="${task.text}"`)
+  }
+
+  if (input.blocker !== undefined) {
+    if (typeof input.blocker !== 'string' || input.blocker.trim().length === 0) {
+      fail('blocker must be a non-empty string')
+    }
+    if (TERMINAL.has(mission.status)) {
+      fail(`mission ${mission.id} is ${mission.status}; a blocker cannot reopen a terminal mission`)
+    }
+    const blockers = /** @type {string[]} */ (mission.blockers)
+    blockers.push(input.blocker.trim())
+    mission.status = 'blocked'
+    changes.push('blocker added')
+  }
+
+  if (input.clear_blockers === true) {
+    mission.blockers = []
+    changes.push('blockers cleared')
+  }
+
+  if (input.note !== undefined) {
+    if (typeof input.note !== 'string' || input.note.trim().length === 0) {
+      fail('note must be a non-empty string')
+    }
+    const notes = /** @type {string[]} */ (mission.notes)
+    notes.push(input.note.trim())
+    changes.push('note added')
+  }
+
+  if (input.scope !== undefined) {
+    if (!['active', 'completed'].includes(mission.status)) {
+      fail(`scope can only be widened for active or completed missions, not ${mission.status}`)
+    }
+    const scope = normalizeScope(input.scope, { allowEmpty: mission.kind === 'survey' })
+    const others = state.missions.filter(
+      (entry) => entry.id !== mission.id && !TERMINAL.has(entry.status) && entry.kind !== 'survey',
+    )
+    const caseInsensitive = state.caseInsensitive === true
+    for (const other of others) {
+      if (mission.kind !== 'survey' && scopesOverlap(scope, other.scope, { caseInsensitive })) {
+        fail(`widened scope overlaps mission ${other.id}; retire it or add an explicit ordering`)
+      }
+    }
+    mission.scope = scope
+    mission.scopeGeneration = (mission.scopeGeneration ?? 1) + 1
+    mission.status = 'active'
+    changes.push('scope widened')
+  }
+
+  if (changes.length === 0) fail('tower_mission requires at least one change')
+  return { changes }
+}