Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

9.2 KB
Raw Blame
import { LoroManager } from '@macro-inc/collaboration/collab/manager';
import type { RawUpdate } from '@macro-inc/collaboration/collab/shared';
import {
  createNoopLiveSyncSource,
  type LiveSyncSource,
} from '@macro-inc/collaboration/collab/source';
import {
  InMemoryWALStore,
  WALSyncer,
} from '@macro-inc/collaboration/collab/wal';
import type { SyncServiceSource } from '@macro-inc/collaboration/sync-service/source';
import { MARKDOWN_LORO_SCHEMA } from '@macro-inc/lexical-core/markdown-loro-schema';
import { Telemetry } from '@macro-inc/observability';
import type { LanguageModel } from 'ai';
import type { LoroDoc } from 'loro-crdt';
import { fastEditor, supervisor } from './ai-editing/agents';
import { PeerPool } from './ai-editing/awareness';
import type { DocumentOp } from './ai-editing/editor';
import type { CodeRunner } from './ai-editing/runtime';
import type { UsageEntry } from './ai-editing/token-tracker';
import type { CoderRunCode, DispatchEditTrace } from './ai-editing/tools';
import { serializeWithXml } from './ai-editing/utils';
import { EditingWorkspace } from './editing-workspace';
import { buildTraceSession, type TraceSession } from './trace-log';

export type Provider = 'anthropic' | 'cerebras' | 'openai' | 'google';

export type Model = {
  provider: Provider;
  model: string;
};

/**
 * `supervised` is the full interpreter → supervisor → coders pipeline.
 * `fast` skips all of that: one model sees the whole document and edits it
 * directly through `runCode`. See ai-editing/agents/fast.ts.
 */
export type EditMode = 'supervised' | 'fast';

export type Models = {
  supervisor: Model;
  interpret: Model;
  coding: Model;
};

/** The three roles of the supervised pipeline. */
export type SupervisedModels = {
  supervisor: LanguageModel;
  interpret: LanguageModel;
  /** Fresh fallback chain per coder, so one coder's fallback state does not
   *  leak into a sibling running in parallel. */
  coding: () => LanguageModel;
};

/**
 * Only the pipeline the request runs is resolved, so a request never touches
 * a provider it will not call: a supervised edit must not fail because the
 * fast chain's key is missing, and vice versa.
 */
export type ResolvedModels = {
  supervised?: SupervisedModels;
  fast?: LanguageModel;
};

/** Who readers see editing: the agent or persona the edit runs as. */
export type Editor = {
  /** Display name, e.g. `Macro`; every cursor this edit draws carries it. */
  name: string;
};

export type RunEditArgs = {
  /** Live sync source, already constructed by the caller (ws in prod). */
  source: LiveSyncSource & Pick<SyncServiceSource, 'doInitialSync'>;
  documentId: string;
  prompt: string;
  models: ResolvedModels;
  mode?: EditMode;
  /** Names the cursors; absent, they read `Macro (AI)`. */
  editor?: Editor;
  /** Snippet runner — QuickJS sandbox in prod, `new Function` in local dev. */
  runner?: CodeRunner;
  typingAnimations?: boolean;
  /** Scales every animation pause; injected so unwatched edits can play faster. */
  sleep?: (ms: number) => Promise<void>;
  signal?: AbortSignal;
  /** Run an intent-interpretation pass before dispatching edits. */
  interpret?: boolean;
  /** Include a markdown trace of all supervisor steps in the result. */
  debug?: boolean;
  /**
   * Commit edits to the shared Loro doc (default true). Set false to have the
   * caller receive the returned `ops` without them being committed.
   */
  propagate?: boolean;
};

export type { UsageEntry };

export type RunEditResult = {
  usage: UsageEntry[];
  ops: DocumentOp[];
  /** Structured trace of the session; stored as JSON, rendered to markdown on demand. */
  session: TraceSession;
  clarification?: string;
  /** The acknowledged version, encoded like sync-service's revisions. Without
   *  propagation nothing is committed, so it is the version the edit started from. */
  revision: string;
};

export async function runEditSession(
  args: RunEditArgs
): Promise<RunEditResult> {
  const source = args.source;

  // The manager owns the one true (merged) doc + mirror.
  const manager = new LoroManager(MARKDOWN_LORO_SCHEMA, {
    documentId: args.documentId,
  });

  await Telemetry.span('edit.sync_init', async (span) => {
    const initialResult = await source.doInitialSync();
    if (initialResult.isErr()) {
      source.cleanup();
      const e = initialResult.error;
      const err = new Error(`initial sync failed: ${e.type} (${e.duration}ms)`);
      span.error(err);
      throw err;
    }
    const initial = initialResult.value;
    span.setAttr('snapshot.bytes', initial.snapshot.byteLength);

    const initResult = await manager.initializeFromSnapshot(initial.snapshot);
    if (initResult.isErr()) {
      source.cleanup();
      const err = new Error(
        `failed to initialize from snapshot: ${initResult.error[0]?.message}`
      );
      span.error(err);
      throw err;
    }
  });

  // When the caller applies the returned ops locally instead, propagating
  // here too would double the content — so route live sync to a no-op sink
  // that acks everything and forwards nothing.
  const shouldPropagate = args.propagate ?? true;
  const startRevision = loroRevision(manager.doc);
  // Typing animations exist for people watching the shared doc. With no
  // propagation nobody can watch, so every animation pause is pure latency —
  // measured at 3.4 s of a 6.3 s fast-mode step.
  const typingAnimations = shouldPropagate ? args.typingAnimations : false;
  const liveSource: LiveSyncSource = shouldPropagate
    ? source
    : createNoopLiveSyncSource(args.documentId);

  const wal = new WALSyncer<RawUpdate>(
    new InMemoryWALStore<RawUpdate>(),
    (updates) => liveSource.pushUpdate(updates)
  );

  // The workspace owns the editing surface + its two-way sync with Loro, and
  // hands out per-coder writers. Under debug it also records a replay trace.
  const { workspace, initialDocument } = await Telemetry.span(
    'edit.hydrate',
    async (span) => {
      const workspace = new EditingWorkspace(manager, liveSource, wal, {
        pool: args.editor ? PeerPool.forEditor(args.editor.name) : undefined,
      });
      const initialDocument = serializeWithXml(workspace.session);
      span.setAttr('document.chars', initialDocument.length);
      return { workspace, initialDocument };
    }
  );

  const allOps: DocumentOp[] = [];
  const coderCodeBlocks: CoderRunCode[][][] = [];
  const dispatchEditTraces: DispatchEditTrace[][] = [];
  const sessionId = crypto.randomUUID();
  const startedAt = new Date();
  try {
    const shared = {
      borrowWriter: () => workspace.borrowWriter(),
      typingAnimations,
      sleep: args.sleep,
      signal: args.signal,
      runner: args.runner,
      onOps: (ops: DocumentOp[]) => allOps.push(...ops),
      onCoderResult: (codes: CoderRunCode[]) => coderCodeBlocks.push([codes]),
      onEditTrace: (edit: DispatchEditTrace) => dispatchEditTraces.push([edit]),
    };
    const {
      totalUsage,
      steps,
      stepDurationsMs,
      intent,
      interpretDurationMs,
      clarification,
    } = await (args.mode === 'fast' ? runFast() : runSupervised());

    async function runSupervised() {
      const models = args.models.supervised;
      if (!models)
        throw new Error('supervised mode requires models.supervised');
      return supervisor(workspace.session, args.prompt, models, {
        ...shared,
        interpret: args.interpret,
      });
    }

    async function runFast() {
      const model = args.models.fast;
      if (!model) throw new Error('fast mode requires models.fast');
      const result = await fastEditor(
        workspace.session,
        args.prompt,
        model,
        shared
      );
      return { ...result, intent: '', interpretDurationMs: undefined };
    }

    // Drain the queued propagates (plus a final catch-all sync) and ensure every
    // commit reached the server before we disconnect. No-op sink when not
    // propagating, so this is harmless either way.
    await Telemetry.span('edit.flush', async (span) => {
      await workspace.flush();
      await wal.flush();
      // The socket closes on abort, so anything still unsent was dropped.
      args.signal?.throwIfAborted();
      const { dirty } = await wal.summary();
      span.setAttr('wal.dirty', dirty);
      if (dirty > 0)
        throw new Error(
          `sync service did not acknowledge ${dirty} document update(s); the edit may have applied`
        );
    });
    const revision = shouldPropagate
      ? loroRevision(manager.doc)
      : startRevision;

    const usage = totalUsage.toEntries();

    const session = buildTraceSession(
      {
        sessionId,
        documentId: args.documentId,
        prompt: args.prompt,
        startedAt,
        initialDocument,
        intent,
        interpretDurationMs,
        coderCodeBlocks,
        dispatchEditTraces,
        stepDurationsMs,
      },
      steps as any,
      usage
    );

    return {
      usage,
      ops: allOps,
      session,
      clarification,
      revision,
    };
  } finally {
    workspace.dispose();
    wal.destroy();
    manager.dispose();
    source.cleanup();
  }
}

/** The doc's version as sync-service reports a revision: base64 of the encoded oplog version. */
function loroRevision(doc: LoroDoc): string {
  return btoa(String.fromCharCode(...doc.oplogVersion().encode()));
}