@abraca/orchestrator 2.3.0

package/src/actions/index.ts

@@ -0,0 +1,197 @@
+/**
+ * Action dispatcher — routes Action.type to the correct executor.
+ */
+import type { ActorConnection } from '../actor-connection.ts'
+import type { Action, TimelineEntry, ServerConfig } from '../types.ts'
+import { executeConnect, executeDisconnect } from './connect.ts'
+import { executeNavigate } from './navigate.ts'
+import { executeType, executeTypeDelete } from './type.ts'
+import { executeMoveCursor, executeSelect } from './cursor.ts'
+import { executeWriteContent, executeDeleteContent } from './content.ts'
+import {
+  executeSetStatus,
+  executeSetAwareness,
+  executeClearAwareness,
+  executePointerMove,
+  executeScrollTo,
+  executeKanbanHover,
+  executeKanbanDrag,
+} from './awareness.ts'
+import { executeCreateDocument, executeMoveDocument, executeSetMeta, executeRenameDocument } from './document.ts'
+import { executeSendChat } from './chat.ts'
+import { executeWait, executeParallel, executeSequence, executeRepeat } from './flow.ts'
+
+export type ActionExecutor = (entry: TimelineEntry) => Promise<void>
+
+export interface ActionContext {
+  actors: Map<string, ActorConnection>
+  serverConfig: ServerConfig
+  vars: Map<string, string>
+}
+
+/**
+ * Resolve variable references in string values.
+ * Replaces ${varName} with the value from vars map.
+ */
+function resolveVars(value: string, vars: Map<string, string>): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, key) => vars.get(key) ?? `\${${key}}`)
+}
+
+function resolveActionVars(action: Action, vars: Map<string, string>): Action {
+  if (vars.size === 0) return action
+
+  // Clone to avoid mutating the original scene definition
+  const a = { ...action } as any
+
+  // Resolve ID fields
+  if (a.docId && typeof a.docId === 'string') a.docId = resolveVars(a.docId, vars)
+  if (a.parentId && typeof a.parentId === 'string') a.parentId = resolveVars(a.parentId, vars)
+  if (a.newParentId && typeof a.newParentId === 'string') a.newParentId = resolveVars(a.newParentId, vars)
+  if (a.cardId && typeof a.cardId === 'string') a.cardId = resolveVars(a.cardId, vars)
+  if (a.toColumnId && typeof a.toColumnId === 'string') a.toColumnId = resolveVars(a.toColumnId, vars)
+
+  // Resolve content fields
+  if (a.text && typeof a.text === 'string') a.text = resolveVars(a.text, vars)
+  if (a.label && typeof a.label === 'string') a.label = resolveVars(a.label, vars)
+  if (a.markdown && typeof a.markdown === 'string') a.markdown = resolveVars(a.markdown, vars)
+  if (a.channel && typeof a.channel === 'string') a.channel = resolveVars(a.channel, vars)
+  if (a.message && typeof a.message === 'string') a.message = resolveVars(a.message, vars)
+
+  return a
+}
+
+export function createExecutor(ctx: ActionContext): ActionExecutor {
+  const execute: ActionExecutor = async (entry: TimelineEntry) => {
+    const action = resolveActionVars(entry.action, ctx.vars)
+    const actor = entry.actor ? ctx.actors.get(entry.actor) : undefined
+
+    switch (action.type) {
+      case 'connect': {
+        if (!actor) throw new Error('connect requires an actor')
+        await executeConnect(actor, ctx.serverConfig)
+        break
+      }
+      case 'disconnect': {
+        if (!actor) throw new Error('disconnect requires an actor')
+        await executeDisconnect(actor)
+        break
+      }
+      case 'navigate': {
+        if (!actor) throw new Error('navigate requires an actor')
+        await executeNavigate(actor, action)
+        break
+      }
+      case 'type': {
+        if (!actor) throw new Error('type requires an actor')
+        await executeType(actor, action)
+        break
+      }
+      case 'typeDelete': {
+        if (!actor) throw new Error('typeDelete requires an actor')
+        await executeTypeDelete(actor, action)
+        break
+      }
+      case 'select': {
+        if (!actor) throw new Error('select requires an actor')
+        await executeSelect(actor, action)
+        break
+      }
+      case 'moveCursor': {
+        if (!actor) throw new Error('moveCursor requires an actor')
+        await executeMoveCursor(actor, action)
+        break
+      }
+      case 'setStatus': {
+        if (!actor) throw new Error('setStatus requires an actor')
+        await executeSetStatus(actor, action)
+        break
+      }
+      case 'setAwareness': {
+        if (!actor) throw new Error('setAwareness requires an actor')
+        await executeSetAwareness(actor, action)
+        break
+      }
+      case 'clearAwareness': {
+        if (!actor) throw new Error('clearAwareness requires an actor')
+        await executeClearAwareness(actor, action)
+        break
+      }
+      case 'createDocument': {
+        if (!actor) throw new Error('createDocument requires an actor')
+        await executeCreateDocument(actor, action, ctx.vars)
+        break
+      }
+      case 'moveDocument': {
+        if (!actor) throw new Error('moveDocument requires an actor')
+        await executeMoveDocument(actor, action)
+        break
+      }
+      case 'renameDocument': {
+        if (!actor) throw new Error('renameDocument requires an actor')
+        await executeRenameDocument(actor, action)
+        break
+      }
+      case 'writeContent': {
+        if (!actor) throw new Error('writeContent requires an actor')
+        await executeWriteContent(actor, action)
+        break
+      }
+      case 'deleteContent': {
+        if (!actor) throw new Error('deleteContent requires an actor')
+        await executeDeleteContent(actor, action)
+        break
+      }
+      case 'setMeta': {
+        if (!actor) throw new Error('setMeta requires an actor')
+        await executeSetMeta(actor, action)
+        break
+      }
+      case 'pointerMove': {
+        if (!actor) throw new Error('pointerMove requires an actor')
+        await executePointerMove(actor, action)
+        break
+      }
+      case 'scrollTo': {
+        if (!actor) throw new Error('scrollTo requires an actor')
+        await executeScrollTo(actor, action)
+        break
+      }
+      case 'kanbanHover': {
+        if (!actor) throw new Error('kanbanHover requires an actor')
+        await executeKanbanHover(actor, action)
+        break
+      }
+      case 'kanbanDrag': {
+        if (!actor) throw new Error('kanbanDrag requires an actor')
+        await executeKanbanDrag(actor, action)
+        break
+      }
+      case 'sendChat': {
+        if (!actor) throw new Error('sendChat requires an actor')
+        await executeSendChat(actor, action)
+        break
+      }
+      case 'wait': {
+        await executeWait(action)
+        break
+      }
+      case 'parallel': {
+        await executeParallel(action, execute)
+        break
+      }
+      case 'sequence': {
+        await executeSequence(action, execute)
+        break
+      }
+      case 'repeat': {
+        await executeRepeat(action, execute)
+        break
+      }
+      default: {
+        throw new Error(`Unknown action type: ${(action as any).type}`)
+      }
+    }
+  }
+
+  return execute
+}

package/src/actions/navigate.ts

@@ -0,0 +1,15 @@
+/**
+ * Navigate action — sets which document an actor is viewing.
+ */
+import type { ActorConnection } from '../actor-connection.ts'
+import type { NavigateAction } from '../types.ts'
+
+export async function executeNavigate(
+  actor: ActorConnection,
+  action: NavigateAction
+): Promise<void> {
+  // Set docId in root awareness (this is what the dashboard watches for presence)
+  actor.setRootAwareness('docId', action.docId)
+  // Pre-load the child provider so subsequent actions on this doc are fast
+  await actor.getChildProvider(action.docId)
+}

package/src/actions/type.ts

@@ -0,0 +1,113 @@
+/**
+ * Typewriter action — character-by-character text insertion with live cursor.
+ *
+ * TipTap Y.js structure: XmlFragment('default') contains:
+ *   [documentHeader, documentMeta, ...body blocks]
+ * Each paragraph is an XmlElement('paragraph') containing XmlText nodes.
+ *
+ * All character indices are relative to body content only (schema nodes skipped).
+ *
+ * TypeDelete action — backspace simulation, deletes characters one at a time.
+ */
+import * as Y from 'yjs'
+import type { ActorConnection } from '../actor-connection.ts'
+import type { TypeAction, TypeDeleteAction } from '../types.ts'
+import { sleep } from '../utils.ts'
+import {
+  ensureDocumentStructure,
+  findTextPosition,
+  fragmentTextLength,
+  getOrCreateLastParagraph,
+  insertParagraphAfter,
+  globalIndexOf,
+} from '../yjs-utils.ts'
+
+export async function executeType(
+  actor: ActorConnection,
+  action: TypeAction
+): Promise<void> {
+  const speed = action.speed ?? 80
+  const variance = action.variance ?? 30
+  const provider = await actor.getChildProvider(action.docId)
+  const doc = provider.document
+  const fragment = doc.getXmlFragment('default')
+
+  // Ensure TipTap schema nodes exist
+  doc.transact(() => ensureDocumentStructure(fragment))
+
+  // Determine starting position
+  const startIndex = action.position ?? fragmentTextLength(fragment)
+
+  // Find the XmlText node at the starting position
+  let currentText: Y.XmlText
+  let currentLocalOffset: number
+
+  const pos = findTextPosition(fragment, startIndex)
+  if (pos) {
+    currentText = pos.text
+    currentLocalOffset = pos.offset
+  } else {
+    const last = getOrCreateLastParagraph(fragment)
+    currentText = last.text
+    currentLocalOffset = currentText.length
+  }
+
+  for (const char of action.text) {
+    const delay = Math.max(10, speed + (Math.random() * 2 - 1) * variance)
+    await sleep(delay)
+
+    if (char === '\n') {
+      // Re-derive global index from current node position (concurrent-safe)
+      const globalIdx = globalIndexOf(fragment, currentText, currentLocalOffset)
+      doc.transact(() => {
+        currentText = insertParagraphAfter(fragment, globalIdx)
+        currentLocalOffset = 0
+      })
+    } else {
+      doc.transact(() => {
+        currentText.insert(currentLocalOffset, char)
+      })
+      currentLocalOffset++
+    }
+
+    // Update cursor — re-derive global position for accuracy
+    const cursorGlobal = globalIndexOf(fragment, currentText, currentLocalOffset)
+    actor.setCursor(action.docId, cursorGlobal)
+  }
+}
+
+export async function executeTypeDelete(
+  actor: ActorConnection,
+  action: TypeDeleteAction
+): Promise<void> {
+  const speed = action.speed ?? 60
+  const variance = action.variance ?? 20
+  const provider = await actor.getChildProvider(action.docId)
+  const doc = provider.document
+  const fragment = doc.getXmlFragment('default')
+
+  // Find starting position
+  const startIndex = action.position ?? fragmentTextLength(fragment)
+  let remaining = action.count
+
+  while (remaining > 0) {
+    const delay = Math.max(10, speed + (Math.random() * 2 - 1) * variance)
+    await sleep(delay)
+
+    // Re-find position each iteration (concurrent-safe)
+    const deleteAt = Math.max(0, startIndex - (action.count - remaining) - 1)
+    const pos = findTextPosition(fragment, deleteAt)
+    if (!pos || deleteAt < 0) break
+
+    doc.transact(() => {
+      if (pos.offset > 0) {
+        pos.text.delete(pos.offset - 1, 1)
+      }
+    })
+
+    remaining--
+
+    // Update cursor
+    actor.setCursor(action.docId, Math.max(0, deleteAt))
+  }
+}

package/src/actor-connection.ts

@@ -0,0 +1,246 @@
+/**
+ * ActorConnection — manages a single actor's connection to the Abracadabra server.
+ * One instance per actor. Handles auth, providers, child caching, awareness, and cursors.
+ */
+import * as Y from 'yjs'
+import { AbracadabraProvider, AbracadabraClient } from '@abraca/dabra'
+import type { ActorDef, ServerConfig } from './types.ts'
+import { loadOrCreateKeypair, deterministicKeypair, signChallenge } from './crypto.ts'
+import { waitForSync, sleep, log } from './utils.ts'
+import { findTextPosition, fragmentTextLength } from './yjs-utils.ts'
+
+interface CachedChild {
+  provider: AbracadabraProvider
+  lastAccessed: number
+}
+
+export class ActorConnection {
+  readonly actor: ActorDef
+  readonly client: AbracadabraClient
+  private _rootDocId: string | null = null
+  private _rootDoc: Y.Doc | null = null
+  private _rootProvider: AbracadabraProvider | null = null
+  private _publicKey: string | null = null
+  private _childCache = new Map<string, CachedChild>()
+
+  constructor(actor: ActorDef, serverConfig: ServerConfig) {
+    this.actor = actor
+    // AbracadabraClient expects an HTTP(S) URL — normalize ws(s):// if provided
+    const httpUrl = serverConfig.url
+      .replace(/^wss:\/\//, 'https://')
+      .replace(/^ws:\/\//, 'http://')
+    this.client = new AbracadabraClient({ url: httpUrl })
+  }
+
+  get rootProvider(): AbracadabraProvider | null {
+    return this._rootProvider
+  }
+
+  get rootDocId(): string | null {
+    return this._rootDocId
+  }
+
+  /** Connect, authenticate, discover root doc, sync, and set awareness. */
+  async connect(serverConfig: ServerConfig): Promise<void> {
+    // Step 1: Get keypair (from file or deterministic from name)
+    const keypair = this.actor.keyFile
+      ? await loadOrCreateKeypair(this.actor.keyFile)
+      : deterministicKeypair(this.actor.name)
+    this._publicKey = keypair.publicKeyB64
+    const signFn = (challenge: string) =>
+      Promise.resolve(signChallenge(challenge, keypair.privateKey))
+
+    // Step 2: Auth (auto-register on first run)
+    try {
+      await this.client.loginWithKey(keypair.publicKeyB64, signFn)
+    } catch (err: any) {
+      const status = err?.status ?? err?.response?.status
+      if (status === 404 || status === 422) {
+        log(`${this.actor.name}: registering new account...`)
+        await this.client.registerWithKey({
+          publicKey: keypair.publicKeyB64,
+          username: this.actor.name.replace(/\s+/g, '-').toLowerCase(),
+          displayName: this.actor.name,
+          deviceName: 'Orchestrator Actor',
+          inviteCode: serverConfig.inviteCode,
+        })
+        await this.client.loginWithKey(keypair.publicKeyB64, signFn)
+      } else {
+        throw err
+      }
+    }
+    log(`${this.actor.name}: authenticated (${keypair.publicKeyB64.slice(0, 12)}...)`)
+
+    // Step 3: Pick an entry-point doc — first Space under the server root,
+    // falling back to the first top-level doc of any kind.
+    const roots = await this.client.listChildren()
+    const firstSpace = roots.find((d) => d.kind === 'space')
+    const rootDocId = (firstSpace ?? roots[0])?.id ?? null
+
+    if (!rootDocId) {
+      throw new Error(`${this.actor.name}: no root document found`)
+    }
+    this._rootDocId = rootDocId
+
+    // Step 4: Connect provider
+    const doc = new Y.Doc({ guid: rootDocId })
+    const provider = new AbracadabraProvider({
+      name: rootDocId,
+      document: doc,
+      client: this.client,
+      disableOfflineStore: true,
+      subdocLoading: 'lazy',
+    })
+    await waitForSync(provider)
+
+    this._rootDoc = doc
+    this._rootProvider = provider
+
+    // Step 5: Set awareness — actors appear as humans (isAgent: false)
+    provider.awareness.setLocalStateField('user', {
+      name: this.actor.name,
+      color: this.actor.color,
+      publicKey: this._publicKey,
+      isAgent: false,
+    })
+    provider.awareness.setLocalStateField('status', null)
+
+    log(`${this.actor.name}: connected to space ${rootDocId}`)
+  }
+
+  /** Get or create a child provider for a document. Caches and sets awareness. */
+  async getChildProvider(docId: string): Promise<AbracadabraProvider> {
+    const cached = this._childCache.get(docId)
+    if (cached) {
+      cached.lastAccessed = Date.now()
+      return cached.provider
+    }
+
+    if (!this._rootProvider) {
+      throw new Error(`${this.actor.name}: not connected`)
+    }
+
+    const childProvider = await this._rootProvider.loadChild(docId)
+    await waitForSync(childProvider)
+
+    childProvider.awareness.setLocalStateField('user', {
+      name: this.actor.name,
+      color: this.actor.color,
+      publicKey: this._publicKey,
+      isAgent: false,
+    })
+
+    this._childCache.set(docId, {
+      provider: childProvider,
+      lastAccessed: Date.now(),
+    })
+
+    return childProvider
+  }
+
+  /**
+   * Set cursor position in a document (collapsed — anchor = head).
+   *
+   * TipTap's yCursorPlugin reads awareness field 'cursor' as
+   * { anchor: RelativePosJSON, head: RelativePosJSON }.
+   * Positions must point into XmlText nodes (not the fragment) with assoc=-1.
+   */
+  setCursor(docId: string, index: number): void {
+    const cached = this._childCache.get(docId)
+    if (!cached) return
+
+    const fragment = cached.provider.document.getXmlFragment('default')
+    const relPos = this._charIndexToRelativePosition(fragment, index)
+    if (!relPos) return
+
+    const json = Y.relativePositionToJSON(relPos)
+    cached.provider.awareness.setLocalStateField('cursor', {
+      anchor: json,
+      head: json,
+    })
+  }
+
+  /** Set text selection range in a document (anchor != head). */
+  setSelection(docId: string, anchor: number, head: number): void {
+    const cached = this._childCache.get(docId)
+    if (!cached) return
+
+    const fragment = cached.provider.document.getXmlFragment('default')
+    const anchorPos = this._charIndexToRelativePosition(fragment, anchor)
+    const headPos = this._charIndexToRelativePosition(fragment, head)
+    if (!anchorPos || !headPos) return
+
+    cached.provider.awareness.setLocalStateField('cursor', {
+      anchor: Y.relativePositionToJSON(anchorPos),
+      head: Y.relativePositionToJSON(headPos),
+    })
+  }
+
+  /**
+   * Convert a character index (body text only, skipping schema nodes)
+   * to a Y.js RelativePosition pointing into the correct XmlText node.
+   * Uses assoc=-1 (associate-left) to match TipTap's cursor behavior.
+   */
+  private _charIndexToRelativePosition(
+    fragment: Y.XmlFragment,
+    charIndex: number
+  ): Y.RelativePosition | null {
+    const totalLen = fragmentTextLength(fragment)
+    const clamped = Math.max(0, Math.min(charIndex, totalLen))
+
+    if (clamped === 0) {
+      // Position at start of fragment — use assoc=-1 on the fragment itself
+      return Y.createRelativePositionFromTypeIndex(fragment, 0, -1)
+    }
+
+    const pos = findTextPosition(fragment, clamped)
+    if (pos) {
+      return Y.createRelativePositionFromTypeIndex(pos.text, pos.offset, -1)
+    }
+
+    // Fallback: end of fragment
+    return Y.createRelativePositionFromTypeIndex(fragment, fragment.length, -1)
+  }
+
+  /** Set a field on root awareness. */
+  setRootAwareness(field: string, value: unknown): void {
+    this._rootProvider?.awareness.setLocalStateField(field, value)
+  }
+
+  /** Set a field on a child document's awareness. */
+  setChildAwareness(docId: string, field: string, value: unknown): void {
+    const cached = this._childCache.get(docId)
+    cached?.provider.awareness.setLocalStateField(field, value)
+  }
+
+  /** Disconnect and clean up all providers. */
+  async disconnect(): Promise<void> {
+    // Clear awareness on children
+    for (const [, cached] of this._childCache) {
+      cached.provider.awareness.setLocalStateField('cursor', null)
+    }
+
+    // Clear root awareness
+    if (this._rootProvider) {
+      this._rootProvider.awareness.setLocalStateField('status', null)
+      this._rootProvider.awareness.setLocalStateField('docId', null)
+    }
+
+    // Wait for awareness updates to propagate before destroying
+    await sleep(150)
+
+    for (const [, cached] of this._childCache) {
+      cached.provider.destroy()
+    }
+    this._childCache.clear()
+
+    if (this._rootProvider) {
+      this._rootProvider.destroy()
+      this._rootProvider = null
+    }
+    this._rootDoc = null
+    this._rootDocId = null
+
+    log(`${this.actor.name}: disconnected`)
+  }
+}