dsh-tower 2.0.4 → 2.1.0

package/types/index.d.ts

@@ -0,0 +1,373 @@
+// Public type contract for the Tower bundle. This is a declaration-only file:
+// the package remains zero-build and no .js is emitted.
+//
+// This is the single vocabulary shared by the published API and the pure
+// domain modules under domain/, which are machine-checked against it by
+// `tsc --noEmit` (checkJs). Keep this file free of value imports so consumers
+// can load it without `allowJs`.
+
+export type MissionStatus = 'planned' | 'active' | 'completed' | 'blocked' | 'paused' | 'merged' | 'abandoned'
+export type MissionKind = 'build' | 'survey'
+export type ReviewStatus = 'clean' | 'p1-1items' | 'p1-2items' | 'p1-3items' | 'p1-4items' | 'p1-5items' | 'p2-1items' | 'p2-2items' | 'p2-3items' | 'p2-4items' | 'p2-5items'
+export type MergeVerdict = 'merge' | 'fix-then-merge' | 'hold'
+export type ReviewPolicy = 'required-clean' | 'none'
+export type FindingType = 'bug' | 'improve' | 'vuln' | 'idea'
+export type FindingSeverity = 'low' | 'medium' | 'high' | 'critical'
+export type FindingStatus = 'open' | 'triaged' | 'fixed' | 'wontfix'
+export type Role = 'worker' | 'reviewer'
+
+export type ErrorCode =
+  | 'invalid-argument'
+  | 'repo-invalid'
+  | 'not-initialized'
+  | 'mission-not-found'
+  | 'finding-not-found'
+  | 'invalid-transition'
+  | 'state-locked'
+  | 'state-corrupt'
+  | 'config-invalid'
+  | 'config-unknown-key'
+  | 'git-timeout'
+  | 'merge-conflict'
+  | 'merge-hook-failed'
+  | 'merge-intent-pending'
+  | 'base-dirty'
+  | 'stale-base'
+  | 'tip-moved'
+  | 'out-of-scope'
+  | 'worker-busy'
+  | 'worker-stale'
+  | 'spawn-unavailable'
+  | 'provider-missing'
+  | 'provider-cooldown'
+  | 'preset-missing'
+  | 'reviewer-prerequisite'
+  | 'worktree-dirty'
+  | 'workspace-busy'
+  | 'worker-limit'
+  | 'rate-limited'
+  | 'takeover-refused'
+  | 'reload-unavailable'
+  | 'reload-failed'
+  | 'tests-failed'
+  | 'tests-timeout'
+  | 'lease-busy'
+  | 'lease-token'
+  | 'batch-invalid'
+  | 'legacy-invalid'
+  | 'tool-internal'
+
+/** One machine-readable gate/completion blocker: a stable code plus a detail. */
+export interface Blocker {
+  code: string
+  detail: string
+}
+
+/** Snapshot inputs for the merge/preflight review, roster and test gates. */
+export interface MergeGateOptions {
+  mission: Mission
+  roster?: RosterEntry[]
+  branch?: string | null
+  branchTip?: string | null
+  review?: Review | null
+  config?: TowerConfig
+  activity?: Record<string, string | undefined>
+  parentStatus?: Record<string, string | null> | null
+  inactiveStates?: Iterable<string>
+  rebaseWaived?: boolean
+}
+
+export interface MissionTask {
+  text: string
+  status: 'open' | 'done' | 'dropped'
+  note?: string
+}
+
+export interface MissionWorktree {
+  path: string
+  branch: string
+  baseCommit: string
+}
+
+export interface CompletionCheck {
+  name?: string
+  command?: string
+  exitCode?: number
+  evidence?: string
+  [key: string]: unknown
+}
+
+export interface CompletionReport {
+  report?: string
+  /** UTF-8 byte length of `report`; absent on documents written before #89. */
+  reportBytes?: number
+  by?: string
+  at?: number
+  checks?: CompletionCheck[]
+}
+
+/** One recorded test-discovery receipt (lib/tests.js). */
+export interface TestRun {
+  version?: number
+  ok?: boolean
+  treeTip?: string | null
+  treeTipAfter?: string | null
+  [key: string]: unknown
+}
+
+/** Record of the last successful rebase of a mission branch. */
+export interface RebaseRecord {
+  at: number
+  oldTip: string
+  newTip?: string
+  baseTip?: string
+}
+
+export interface Mission {
+  id: string
+  title: string
+  status: MissionStatus
+  kind: MissionKind
+  scope: string[]
+  deps: string[]
+  /**
+   * Optional because the pure domain helpers tolerate partial/legacy mission
+   * snapshots (`mission.tasks ?? []`); a mission loaded through validateState
+   * always has an array.
+   */
+  tasks?: MissionTask[]
+  blockers?: string[]
+  reviewPolicy?: ReviewPolicy
+  reviewExemptionReason?: string | null
+  worktree?: MissionWorktree | null
+  owner?: string | null
+  notes?: string[]
+  completionReport?: CompletionReport | null
+  testRuns?: TestRun[]
+  rebase?: RebaseRecord | null
+  mergedCommit?: string | null
+  mergedAt?: number | null
+  scopeGeneration?: number
+  ownerGeneration?: number
+  pauseCause?: string | null
+  updatedAt?: number
+  references?: string[]
+  authorizationRef?: string | null
+}
+
+/**
+ * Compact archived-mission entry (`archive/index.json`). It keeps enough of the
+ * mission for ordering, dependency lookups and id allocation without loading the
+ * full year file, and it is what `tower_status includeArchived` pages from (#73).
+ */
+export interface ArchiveIndexEntry {
+  id: string
+  title: string
+  status: MissionStatus
+  kind?: MissionKind
+  scope?: string[]
+  deps?: string[]
+  owner?: string | null
+  branch?: string | null
+  mergedCommit?: string | null
+  mergedAt?: number | null
+  updatedAt?: number | null
+  archivedAt: number
+  archivedYear: number
+}
+
+/** Full archived record (`archive/<year>.json`): mission + linked history. */
+export interface ArchivedMissionRecord extends ArchiveIndexEntry {
+  mission: Mission
+  reviews: Review[]
+  findings: Finding[]
+}
+
+export interface Review {
+  id?: string
+  seq?: number
+  missionId: string
+  branch: string
+  round: number
+  status: string
+  mergeVerdict: MergeVerdict
+  reviewedCommit: string
+  at: number
+  findings?: string
+  checks?: string[]
+  decision?: string
+  reviewer?: string
+  reviewerRole?: string
+  breakGlassReason?: string
+}
+
+export interface Finding {
+  id: string
+  type: FindingType
+  title: string
+  seq?: number | null
+  severity?: FindingSeverity | null
+  status?: FindingStatus | null
+  missionId?: string | null
+  branch?: string | null
+  reportedBy?: string | null
+  at?: number | null
+  updatedAt?: number | null
+  closedAt?: number | null
+  summary?: string
+  details?: string
+  suggestedFix?: string
+  location?: string
+}
+
+export interface RosterEntry {
+  name: string
+  role: Role
+  state: string
+  /** Reserved rows may exist before an agent id is known. */
+  agentId?: string | null
+  missionId?: string | null
+  parentSessionId?: string | null
+  spawnTip?: string | null
+  stale?: boolean
+  [key: string]: unknown
+}
+
+/**
+ * Public state contract. This stays hand-written rather than derived from
+ * `Static<typeof StateSchema>` because the validator schema is deliberately
+ * tolerant of legacy rows (`additionalProperties`, optional collections) and
+ * checks status vocabularies/worktree records semantically after the shape
+ * pass. `tests/type-contracts.ts` pins the schema/public-type overlap.
+ */
+export interface TowerState {
+  schemaVersion: number
+  revision: number
+  base: string
+  missions: Mission[]
+  repoRoot?: string
+  commonDir?: string
+  createdAt?: number
+  updatedAt?: number
+  dirtyBase?: boolean
+  /** Detected once at tower_init; null means "not detected yet" (#90). */
+  caseInsensitive?: boolean | null
+  towerAgentId?: string | null
+  snapshotCommit?: string | null
+  snapshotRef?: string | null
+  roster?: RosterEntry[]
+  reviews?: Review[]
+  findings?: Finding[]
+  messages?: Array<Record<string, unknown>>
+  batches?: Array<Record<string, unknown>>
+  legacySnapshots?: Array<Record<string, unknown>>
+  legacyMaps?: Array<Record<string, unknown>>
+  deliveries?: Array<Record<string, unknown>>
+  mergeIntent?: Record<string, unknown> | null
+  rebaseIntent?: Record<string, unknown> | null
+  messageSeq?: number
+  reviewSeq?: number
+  findingSeq?: number
+  batchSeq?: number
+  deliverySeq?: number
+}
+
+export type TowerConfig = import('@deepseek-ai/schemastery').TypeS<typeof import('../domain/config/schema.js').Config>
+
+/** Counts rendered by mission summaries and the board. */
+export interface TaskCounts {
+  total: number
+  done: number
+  open: number
+  dropped: number
+}
+
+/** Compact mission view returned by tower_plan/tower_status. */
+export interface MissionSummary {
+  id: string
+  title: string
+  kind: MissionKind
+  status: MissionStatus
+  scope: string[]
+  deps: string[]
+  owner: string | null
+  worktree: MissionWorktree | null
+  blockers: string[]
+  tasks: TaskCounts
+  scopeGeneration: number
+  ownerGeneration: number
+  pauseCause: string | null
+  reviewPolicy: ReviewPolicy
+  mergedCommit: string | null
+  mergedAt: number | null
+  /** Size of the completion report without loading its body; null when absent. */
+  reportBytes: number | null
+  updatedAt?: number
+}
+
+/** Full mission view returned by mission-scoped use cases. */
+export interface MissionDetail extends Omit<MissionSummary, 'tasks'> {
+  tasks: MissionTask[]
+  notes: string[]
+  completionReport: CompletionReport | null
+  authorizationRef: string | null
+  references: string[]
+  reviewExemptionReason: string
+  testRuns: TestRun[]
+}
+
+export interface FindingSummary {
+  id: string
+  seq: number | null
+  type: FindingType
+  title: string
+  severity: FindingSeverity | null
+  status: FindingStatus
+  missionId: string | null
+  branch: string | null
+  reportedBy: string | null
+  at: number | null
+  updatedAt: number | null
+  closedAt: number | null
+}
+
+export interface ToolDefinition {
+  name: string
+  description: string
+  parameters: { type: 'object'; properties: Record<string, unknown>; required?: string[] }
+  execute(args: Record<string, unknown>, exec: { agent?: { id?: string } }): Promise<unknown>
+}
+
+/** Owned Tower mode state exposed as the `tower` Cordis service. */
+export interface ModeStateService {
+  has(key: string): boolean
+  get(key: string): unknown
+  set(key: string, value: unknown): this
+  delete(key: string): boolean
+  values(): IterableIterator<unknown>
+  entries(): IterableIterator<[string, unknown]>
+  replace(entries?: Iterable<[string, unknown]>): void
+  clear(): void
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    tower?: ModeStateService
+  }
+}
+
+import type { Static, TSchema } from '@sinclair/typebox'
+
+export type DefineTool = <S extends TSchema>(
+  ctx: any,
+  definition: {
+    name: string
+    description: string
+    parameters: S
+    execute(args: Static<S>, exec: any): Promise<unknown>
+    aliases?: any
+    requiresMissionId?: any
+    board?: any
+    output?: any
+  },
+) => void

package/lib/errors.js

@@ -1,123 +0,0 @@
-// Stable tool error codes.
-//
-// Everything a Tower tool throws reaches the model as
-//   [tower:<code>] <original message>
-// so callers (and tests) can branch on the code instead of matching prose.
-// The catalog is documented in docs/reference/errors.md; scripts/check-docs.mjs
-// keeps the two in sync.
-import { GitError } from './git.js'
-
-export const ERROR_CODES = {
-  'invalid-argument': 'A tool argument is missing, malformed, or not allowed.',
-  'repo-invalid': 'repoRoot is missing, relative, or not inside a Git repository.',
-  'not-initialized': 'Tower is not initialized for this repository; run tower_init.',
-  'mission-not-found': 'No mission with that id exists.',
-  'finding-not-found': 'No finding with that id exists.',
-  'invalid-transition': 'The requested state transition is not allowed.',
-  'state-locked': 'Another Tower writer holds the state lock.',
-  'state-corrupt': 'The Tower state file is unreadable or invalid.',
-  'config-invalid': 'Tower configuration is invalid.',
-  'config-unknown-key': 'Tower configuration has an unknown top-level key.',
-  'git-failed': 'A git command failed.',
-  'git-timeout': 'A git command timed out or exceeded its output buffer.',
-  'worktree-dirty': 'The mission worktree has uncommitted changes and cannot complete.',
-  'spawn-unavailable': 'The subagents service is unavailable.',
-  'provider-missing': 'No subagent provider is registered.',
-  'preset-missing': 'The configured agent preset is not registered.',
-  'reviewer-prerequisite': 'The reviewer spawn prerequisite is not met.',
-  'not-authorized': 'The calling agent role may not perform this action.',
-  'workspace-busy': 'Another Tower session owns this repository workspace lock.',
-  'worker-limit': 'The repository reached spawn.maxLiveWorkers live workers.',
-  'rate-limited': 'The tower_send per-minute rate limit was reached.',
-  'takeover-refused': 'The mission already has a live worker that was not stopped first.',
-  'reload-unavailable': 'The DSH HMR service is not available in this profile.',
-  'reload-failed': 'The HMR reload failed; check the DSH log and restart if needed.',
-  'tests-failed': 'Declared test discovery failed or did not meet its admission requirements.',
-  'tests-timeout': 'Test discovery exceeded its time or output budget.',
-  'lease-busy': 'Another holder owns the requested advisory lease.',
-  'lease-token': 'The lease release token does not match the current holder.',
-  'batch-invalid': 'The batch request or its close evidence is invalid.',
-  'legacy-invalid': 'The legacy snapshot or mapping is invalid.',
-  'tool-internal': 'An unexpected failure; read the message and the activity log.',
-}
-
-export class TowerToolError extends Error {
-  constructor(code, message, options = {}) {
-    super(`[tower:${code}] ${message}`, options.cause ? { cause: options.cause } : undefined)
-    this.name = 'TowerToolError'
-    this.code = code
-    this.retryable = options.retryable === true
-    this.nextAction = options.nextAction ?? null
-    this.details = options.details ?? null
-  }
-}
-
-// Ordered rules; the first match wins. Keep the specific patterns above the
-// generic argument fallback so `no open task matching` never becomes internal.
-const RULES = [
-  ['not-initialized', /tower is not initialized/i],
-  ['mission-not-found', /^unknown mission "/i],
-  ['finding-not-found', /^unknown finding "/i],
-  ['state-locked', /locked by another writer/i],
-  [
-    'state-corrupt',
-    /corrupt tower state|^tower state |^unsupported tower state|^invalid (?:mission|roster|message|finding|review) entry|^mission entry without id|^duplicate (?:mission|roster|message|finding|review)|^mission .* (?:has unknown status|has no tasks array|has no deps array)|^message .* has no readBy array|^finding .* has unknown status|^review .* has unknown (?:status|merge verdict)/i,
-  ],
-  ['config-unknown-key', /unknown key|unknown top-level key/i],
-  ['config-invalid', /config (?:is invalid|must be an object)|repo config/i],
-  ['lease-busy', /lease .* (?:held|owned)|another holder owns/i],
-  ['lease-token', /lease .*token|token does not match/i],
-  ['tests-timeout', /test discovery .*(?:timed out|exceeded|too large)/i],
-  ['tests-failed', /test discovery (?:failed|did not)|tests? (?:failed|missing|did not pass)/i],
-  ['batch-invalid', /batch (?:is invalid|close|member|receipt)/i],
-  ['legacy-invalid', /legacy (?:snapshot|map|source)|unsupported legacy/i],
-  ['spawn-unavailable', /subagents service is unavailable/i],
-  ['provider-missing', /no subagent provider/i],
-  ['preset-missing', /agent preset .*is not registered/i],
-  ['reviewer-prerequisite', /reviewer needs an existing|reviewer requires a completed/i],
-  ['repo-invalid', /repoRoot is required|repoRoot must be an absolute path/i],
-  ['workspace-busy', /workspace .*lock|another tower session owns/i],
-  ['worker-limit', /live worker limit|too many live workers|worker limit reached/i],
-  ['rate-limited', /rate limit|too many tower messages/i],
-  ['takeover-refused', /takeover refused|cannot take over/i],
-  ['not-authorized', /only the tower|only an assigned reviewer|only the tower or a worker|does not own mission|not authorized|may not perform this action/i],
-  [
-    'invalid-transition',
-    /cannot move from|cannot be completed from that state|is already completed|merged is recorded only|can only be widened|only a completed mission|reviewers may list and read|still has \d+ open task|has unresolved blockers|has no worktree|has no commits since|cannot complete with \d+ unread inbox|not assigned to mission|is a [a-z]+, not a worker|cannot reanchor base|worktree is missing|worktree .* is not a Git worktree|belongs to a different repository|is on .* expected|has \d+ live worker|already has a live worker|cannot reopen a terminal mission|stopped worker cannot report completion|can only be spawned|violates? (?:the )?mission (?:state|transition)/i,
-  ],
-  [
-    'invalid-argument',
-    /requires |is required|must be (?:a|an|one|an integer|non-empty|printable)|must not be|must be one of|no open task matching|unknown mission status|unknown finding severity|unknown finding type|not an array|is not an array|scope must|title must|checks must|role must|timeoutMs must|repoRoot is required|only a list filter|snapshotDirty was requested|refusing to send a message to yourself|mission has \d+ live worker|roster name already used|is already in the roster|depends on unknown mission/i,
-  ],
-]
-
-function originalMessage(error) {
-  return String(error?.message ?? error)
-}
-
-/** Wrap any thrown value into a TowerToolError with a stable code. */
-export function classifyError(error) {
-  if (error instanceof TowerToolError) return error
-  if (error && typeof error.code === 'string' && ERROR_CODES[error.code]) {
-    return new TowerToolError(error.code, originalMessage(error), {
-      cause: error,
-      retryable: error.retryable === true,
-      nextAction: error.nextAction ?? null,
-      details: error.details ?? null,
-    })
-  }
-  if (error instanceof GitError || error?.name === 'GitError') {
-    const message = originalMessage(error)
-    if (/not a git repository/i.test(message)) return new TowerToolError('repo-invalid', message, { cause: error })
-    const code = error?.timedOut === true || error?.bufferOverflow === true ? 'git-timeout' : 'git-failed'
-    return new TowerToolError(code, message, { cause: error })
-  }
-  const message = originalMessage(error)
-  const RETRYABLE = new Set(['state-locked', 'rate-limited', 'git-timeout', 'workspace-busy', 'merge-intent-pending'])
-  for (const [code, pattern] of RULES) {
-    if (pattern.test(message)) {
-      return new TowerToolError(code, message, { cause: error, retryable: RETRYABLE.has(code) })
-    }
-  }
-  return new TowerToolError('tool-internal', message, { cause: error })
-}