@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/src/types.ts

@@ -0,0 +1,432 @@
+/**
+ * Shared contracts for dsh-data-table: sheet data (agent ↔ renderer)
+ * and the workbook model (agent tools ↔ node half ↔ browser canvas).
+ * @module dsh-data-table/types
+ */
+
+import type { LineageContext } from '#contracts'
+import type { VersionKind } from '#contracts'
+
+export type SheetColumnType = 'string' | 'number' | 'boolean' | 'date' | 'currency'
+
+export interface SheetColumn {
+  /** Unique key (English identifier, mirrors the row field). */
+  key: string
+  /** Header label (Chinese copy is fine). */
+  label: string
+  type: SheetColumnType
+}
+
+export interface SheetMeta {
+  /** Data source description (e.g. SQL / file path). */
+  source?: string
+  /** Generating SQL — data lineage. */
+  query?: string
+  /** ISO timestamp. */
+  generatedAt?: string
+  /** User-facing notes. */
+  notes?: string
+  lineage?: LineageContext
+}
+
+/** Persisted schema for an Agent-managed sheet. */
+export interface SheetSchema {
+  version: number
+  columns: SheetColumn[]
+  /** Number of data rows, excluding the header row. */
+  rowCount: number
+  updatedAt: string
+}
+
+export interface SheetData {
+  /** Sheet name (panel title). */
+  name: string
+  columns: SheetColumn[]
+  rows: Array<Record<string, unknown>>
+  meta?: SheetMeta
+}
+
+/** Row/column caps enforced by the host tool (documented in the tool schema). */
+/** Univer is a UI projection, not an unlimited database. Keep local imports
+ * bounded at 100k rows; larger tables should use a columnar backend. */
+export const SHEET_MAX_ROWS = 100000
+/** Keep one large Agent append from monopolizing one Univer mutation frame. */
+export const SHEET_MAX_APPEND_ROWS = 1000
+/** Physical row indexes include the header row at index 0. */
+export const SHEET_MAX_PHYSICAL_ROWS = SHEET_MAX_ROWS + 1
+export const SHEET_MAX_COLUMNS = 50
+export const SHEET_MAX_NAME = 64
+
+/** Whether a parsed tool-argument value is a well-formed sheet. */
+export function isSheetData(value: unknown): value is SheetData {
+  if (typeof value !== 'object' || value === null) return false
+  const sheet = value as Record<string, unknown>
+  if (typeof sheet.name !== 'string' || sheet.name.length === 0) return false
+  if (!Array.isArray(sheet.columns) || !Array.isArray(sheet.rows)) return false
+  return sheet.columns.every(column => {
+    if (typeof column !== 'object' || column === null) return false
+    const c = column as Record<string, unknown>
+    return typeof c.key === 'string' && typeof c.label === 'string'
+      && (c.type === 'string' || c.type === 'number' || c.type === 'boolean' || c.type === 'date' || c.type === 'currency')
+  })
+}
+
+/** Default workbook id (backward compatible with pre-workbook writes). */
+export const DEFAULT_WORKBOOK = 'main'
+
+/**
+ * One named workbook: an Univer-compatible snapshot on disk (the whole state,
+ * sheets included). The agent addresses workbooks across sessions by id; the
+ * browser mounts a residency instance from the current snapshot.
+ */
+export interface WorkbookMeta {
+  id: string
+  name: string
+  /** Sheet ids in display order (Univer snapshot convention). */
+  sheetOrder: string[]
+  /** ISO timestamp of the last save. */
+  updatedAt: string
+  /** Monotonically increasing revision of the workbook. */
+  revision?: number
+  /** Revision represented by the persisted snapshot sidecar. */
+  snapshotRevision?: number
+  /** Append-only operations used by replay, browser projection and audit UI. */
+  operations?: WorkbookOperation[]
+  /** Durable agent proposals awaiting user confirmation. */
+  proposals?: WorkbookProposal[]
+  /** Last known checkpoints used by rollback. */
+  checkpoints?: WorkbookCheckpoint[]
+  /** Univer workbook snapshot (sheets → cellData etc.). */
+  snapshot: unknown
+}
+
+export type WorkbookActor = 'agent' | 'user'
+/**
+ * Lifecycle of a user-visible Version. `temporary` is retained only so old
+ * persisted operation logs can still be read; new writes use `open`.
+ */
+export type WorkbookVersionStatus = 'open' | 'final' | 'restored' | 'superseded' | 'temporary'
+
+/** Ephemeral collaboration state. Presence is broadcast live but never bumps
+ * the workbook revision or enters the durable operation log. */
+export type WorkbookPresenceKind = 'selection' | 'editing' | 'active-sheet'
+
+export interface WorkbookPresencePayload {
+  kind: WorkbookPresenceKind
+  payload: Record<string, unknown>
+}
+
+/** Current Univer range plus a bounded value preview for composer context. */
+export interface WorkbookSelectionRange {
+  sheetId: string
+  sheetName: string
+  startRow: number
+  startColumn: number
+  endRow: number
+  endColumn: number
+  values: readonly (readonly unknown[])[]
+}
+
+/** Coordinates the resident canvas can focus from a bridge reference. */
+export interface WorkbookFocusRange {
+  sheetId: string
+  startRow: number
+  startColumn: number
+  endRow: number
+  endColumn: number
+}
+
+export interface WorkbookPresence {
+  workbookId: string
+  sessionId: string
+  actor: WorkbookActor
+  kind: WorkbookPresenceKind
+  payload: Record<string, unknown>
+  timestamp: string
+}
+
+/** Isolated review workspace lifecycle. The trunk workbook is never mutated
+ * until a worktree is explicitly merged. */
+export type WorkbookWorktreeStatus = 'draft' | 'ready' | 'merged' | 'discarded'
+
+export type WorkbookOperationType =
+  | 'update_cells'
+  | 'clear_range'
+  | 'delete_cells'
+  | 'insert_rows'
+  | 'delete_rows'
+  | 'insert_columns'
+  | 'delete_columns'
+  | 'create_sheet'
+  | 'delete_sheet'
+  | 'rename_sheet'
+  | 'append_rows'
+  | 'format_cells'
+  | 'merge_cells'
+  | 'unmerge_cells'
+  | 'freeze_panes'
+  | 'set_column_width'
+  | 'set_row_height'
+  | 'sort_range'
+  | 'set_hyperlink'
+  | 'remove_hyperlink'
+  /** Legacy-only operation retained so existing persisted histories can replay. */
+  | 'remove_duplicates'
+  | 'batch'
+  | 'snapshot_replace'
+
+/** How a deleted cell range affects neighboring cells. */
+export type WorkbookCellDeleteShift = 'clear' | 'left' | 'up'
+
+export type WorkbookCellValue = string | number | boolean | null
+
+export interface WorkbookCellUpdate {
+  row: number
+  column: number
+  value: WorkbookCellValue
+  /** Optional Univer formula, without the leading display-only metadata. */
+  formula?: string
+}
+
+/** A browser-side edit that can be persisted without serializing the workbook. */
+export interface WorkbookLocalChange {
+  type: 'update_cells'
+  payload: {
+    sheetId: string
+    cells: WorkbookCellUpdate[]
+  }
+}
+
+export interface WorkbookRange {
+  startRow: number
+  startColumn: number
+  endRow: number
+  endColumn: number
+}
+
+export interface WorkbookOperationPayload {
+  sheetId?: string
+  sheetName?: string
+  cells?: WorkbookCellUpdate[]
+  range?: WorkbookRange
+  count?: number
+  shift?: WorkbookCellDeleteShift
+  name?: string
+  columns?: SheetColumn[]
+  rows?: Array<Record<string, unknown>>
+  /** Source-backed import is normalized to append_rows before persistence. */
+  sourcePath?: string
+  sourceFormat?: string
+  meta?: SheetMeta
+  schema?: SheetSchema
+  style?: WorkbookCellStyle
+  merge?: WorkbookRange
+  freeze?: { rows?: number; columns?: number }
+  size?: number
+  sort?: { column: number; direction?: 'asc' | 'desc' }
+  /** Hyperlink applied to the top-left cell of the range. */
+  url?: string
+  label?: string
+  /**
+   * Row that holds the column headers for `append_rows`; data starts on the row
+   * below it. Defaults to 0, which is the only behaviour the tool had before the
+   * field existed, so an omitted value keeps every existing caller intact.
+   * Report sheets keep their title block above the real header row, and this is
+   * what lets them be appended to instead of forcing a rewrite through
+   * `update_cells`.
+   */
+  headerRowIndex?: number
+  /**
+   * When false, `append_rows` skips comparing existing header labels against the
+   * incoming column labels. Structure still has to be one column per column —
+   * this only relaxes the text match. Defaults to true.
+   */
+  verifyHeader?: boolean
+  /** Legacy-only remove-duplicates payload fields; no longer exposed as tools/UI. */
+  dedupeColumns?: number[]
+  hasHeader?: boolean
+  keep?: 'first' | 'last'
+  /** Server-computed original row indexes removed by remove_duplicates. */
+  removedRows?: number[]
+  operations?: Array<{ type: WorkbookOperationType; payload: WorkbookOperationPayload }>
+  snapshot?: unknown
+}
+
+/** A small, JSON-safe subset of Univer cell styles used by Agent tools. */
+export interface WorkbookCellStyle {
+  ff?: string
+  fs?: number
+  bl?: boolean
+  it?: boolean
+  ul?: boolean
+  st?: boolean
+  bg?: string
+  cl?: string
+  ht?: number
+  vt?: number
+  tr?: number
+  n?: string
+}
+
+/** A durable, replayable mutation shared by Agent and user edits. */
+export interface WorkbookOperation {
+  opId: string
+  workbookId: string
+  revision: number
+  /** Logical parent version. Normally revision - 1; rollback versions point
+   * back to the selected target while retaining their global revision number. */
+  parentRevision?: number
+  /** Revision observed by the author before this operation was submitted. */
+  baseRevision?: number
+  /** Stable logical Version id. Multiple physical revisions may fill one
+   * open user Version until it reaches the ten-step target. */
+  versionId?: string
+  /** Open Versions accept additional user steps; final Versions do not. */
+  versionStatus?: WorkbookVersionStatus
+  /** User-facing semantic description of this Version, supplied by the Host. */
+  versionSummary?: string
+  /**
+   * v3 Version tier (PRD §4). Absent on operations written before v3; the
+   * projection then derives it from summary/actor, so old logs still classify.
+   */
+  versionKind?: VersionKind
+  /** Optional Agent intent retained for audit without changing Step payloads. */
+  versionIntent?: string
+  /** Correlates multiple semantic Versions emitted by one Agent run. */
+  agentRunId?: string
+  /** Cross-plugin task/subtask/run lineage for this durable mutation. */
+  lineage?: LineageContext
+  /** Source revision selected by a restore Version. */
+  restoredFromRevision?: number
+  actor: WorkbookActor
+  type: WorkbookOperationType
+  timestamp: string
+  payload: WorkbookOperationPayload
+  /**
+   * Derived, human summary of this Step (v3.1). Set by the server when the
+   * caller's operation is generic — a whole-snapshot save describes itself as
+   * `替换 workbook 快照`, which said nothing about *what* changed.
+   */
+  stepSummary?: string
+  /** Stable request digest used to detect accidental opId reuse with new data. */
+  requestHash?: string
+}
+
+/** One replayable atomic step inside a version. */
+export interface WorkbookHistoryStep {
+  index: number
+  opId: string
+  type: WorkbookOperationType
+  summary: string
+  /**
+   * The revision this Step left behind — the state *after* it.
+   *
+   * Optional because a Step built from a history entry that predates the field
+   * has no revision of its own; a comparison then falls back to the Version's.
+   * Carrying it is what lets a Step be a comparison baseline and not only a
+   * thing to look at.
+   */
+  revision?: number
+}
+
+/** Version-first history entry. Steps are available to the client but can be
+ * collapsed in the default history view. */
+export interface WorkbookHistoryVersion {
+  versionId: string
+  /** Display number (`V1`, `V2`) assigned in creation order; never reused. */
+  number: number
+  startRevision: number
+  revision: number
+  parentRevision: number
+  actor: WorkbookActor
+  timestamp: string
+  summary: string
+  /** v3 tier: `named` for a manual save / Agent call / restore, else `auto`. */
+  kind: VersionKind
+  intent?: string
+  agentRunId?: string
+  lineage?: LineageContext
+  restoredFromRevision?: number
+  /** Display number of the Version a restore reinstated (v3 origin label). */
+  restoredFromNumber?: number
+  stepCount: number
+  steps: WorkbookHistoryStep[]
+  canPreview: boolean
+  status: WorkbookVersionStatus
+  branch: 'main' | 'superseded'
+}
+
+/** Durable isolated workbook workspace used for reviewable changes. */
+export interface WorkbookWorktree {
+  id: string
+  workbookId: string
+  /** Opaque browser/agent session that owns this worktree. */
+  ownerSessionId: string
+  name: string
+  baseRevision: number
+  revision: number
+  status: WorkbookWorktreeStatus
+  createdAt: string
+  updatedAt: string
+  snapshot: unknown
+  operations: WorkbookOperation[]
+}
+
+/** Payload-light worktree entry for catalog and UI lists. */
+export interface WorkbookWorktreeSummary {
+  id: string
+  workbookId: string
+  ownerSessionId: string
+  name: string
+  baseRevision: number
+  revision: number
+  status: WorkbookWorktreeStatus
+  createdAt: string
+  updatedAt: string
+}
+
+export type WorkbookProposalStatus = 'pending' | 'committed' | 'rejected' | 'expired'
+
+export interface WorkbookProposal {
+  id: string
+  workbookId: string
+  actor: WorkbookActor
+  baseRevision: number
+  createdAt: string
+  updatedAt: string
+  status: WorkbookProposalStatus
+  summary: string
+  changes: WorkbookChange[]
+  snapshot: unknown
+  committedRevision?: number
+}
+
+export interface WorkbookChange {
+  kind: 'cell' | 'sheet' | 'structure'
+  sheetId?: string
+  sheetName?: string
+  row?: number
+  column?: number
+  before?: unknown
+  after?: unknown
+  /** The value is unchanged on both sides; only the cell's formatting moved. */
+  styleOnly?: boolean
+  description?: string
+}
+
+export interface WorkbookCheckpoint {
+  revision: number
+  actor: WorkbookActor
+  timestamp: string
+  snapshot: unknown
+}
+
+/** Tool result for workbook listing/open. */
+export interface WorkbookSummary {
+  id: string
+  name: string
+  sheets: Array<{ id: string; name: string; schema?: SheetSchema }>
+  updatedAt: string
+  /** Current trunk revision; lets `workbook_catalog(action=list)` feed `baseRevision` without a second read. */
+  revision?: number
+}