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.

15.4 KB
Raw Blame
import { type Span, Telemetry } from '@macro-inc/observability';
import { type LanguageModel, tool } from 'ai';
import { z } from 'zod';
import type { coder } from '../agents';
import type { LexicalSession } from '../ai-toolkit';
import type { AwarenessSource } from '../awareness';
import type { Doc } from '../doc';
import type { DocumentOpQueueParams } from '../queue';
import type { TokenTracker } from '../token-tracker';
import { numberLines, serializeWithXml } from '../utils';
import {
  type RunCodeToolOptions,
  type SnippetPair,
  snippetsToRecord,
} from './run-code';

export type { UsageEntry } from '../token-tracker';
export { TokenTracker } from '../token-tracker';

type BlockedReport = {
  message: string;
};
type ContextRange = {
  startLine: number;
  endLine: number;
  rootIds: string[];
  ids: string[];
  source: 'ids' | 'full-document';
};

const ID_PATTERN = /[A-Za-z0-9_~-]{6,}/g;
const BLOCK_TAGS = new Set([
  'h1',
  'h2',
  'h3',
  'h4',
  'h5',
  'h6',
  'p',
  'blockquote',
  'li',
  'table',
  'ul',
  'ol',
]);
const CONTAINER_TAGS = new Set(['table', 'ul', 'ol']);

type XmlNodeRange = {
  tag: string;
  id: string;
  startLine: number;
  endLine: number;
  ancestors: XmlNodeRange[];
};

/** Pull a writer'session `reportBlocked` payload out of its run, if it bailed. */
function findBlocked(
  res: Awaited<ReturnType<typeof coder>>
): BlockedReport | null {
  for (const step of res.steps) {
    for (const call of step.toolCalls) {
      if (call.toolName === 'reportBlocked') return call.input as BlockedReport;
    }
  }
  return null;
}

export function mergeRanges(
  ranges: Array<[number, number]>
): Array<[number, number]> {
  const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
  const merged: Array<[number, number]> = [];
  for (const range of sorted) {
    const last = merged[merged.length - 1];
    if (last && range[0] <= last[1] + 1) last[1] = Math.max(last[1], range[1]);
    else merged.push([range[0], range[1]]);
  }
  return merged;
}

export function indexXmlRanges(xml: string): {
  lines: string[];
  byId: Map<string, XmlNodeRange>;
} {
  const lines = xml.split('\n');
  const byId = new Map<string, XmlNodeRange>();
  const stack: XmlNodeRange[] = [];
  const tagPattern = /<\/?([A-Za-z][A-Za-z0-9_-]*)([^>]*)>/g;

  for (let i = 0; i < lines.length; i++) {
    const line = lines[i]!;
    tagPattern.lastIndex = 0;
    for (
      let match = tagPattern.exec(line);
      match !== null;
      match = tagPattern.exec(line)
    ) {
      const [raw, tag, attrs] = match;
      if (raw.startsWith('</')) {
        for (let j = stack.length - 1; j >= 0; j--) {
          const node = stack[j]!;
          stack.pop();
          node.endLine = i + 1;
          if (node.tag === tag) break;
        }
        continue;
      }

      const id = attrs.match(/\bid="([^"]+)"/)?.[1];
      const selfClosing = raw.endsWith('/>');
      if (!id) continue;

      const node: XmlNodeRange = {
        tag,
        id,
        startLine: i + 1,
        endLine: i + 1,
        ancestors: [...stack],
      };
      byId.set(id, node);
      if (!selfClosing) stack.push(node);
    }
  }

  for (const node of stack) node.endLine = lines.length;
  return { lines, byId };
}

function containingRoot(node: XmlNodeRange): XmlNodeRange {
  const lineage = [...node.ancestors, node];
  for (let i = lineage.length - 1; i >= 0; i--) {
    const current = lineage[i]!;
    if (CONTAINER_TAGS.has(current.tag)) return current;
  }
  for (let i = lineage.length - 1; i >= 0; i--) {
    const current = lineage[i]!;
    if (BLOCK_TAGS.has(current.tag)) return current;
  }
  return node;
}

export function computeContextRange(
  xml: string,
  instruction: string
): ContextRange {
  const { lines, byId } = indexXmlRanges(xml);
  const ids = [...new Set(instruction.match(ID_PATTERN) ?? [])].filter((id) =>
    byId.has(id)
  );
  if (ids.length > 0) {
    const roots = ids.map((id) => containingRoot(byId.get(id)!));
    const ranges = mergeRanges(
      roots.map((root) => [root.startLine, root.endLine])
    );
    return {
      startLine: ranges[0]![0],
      endLine: ranges[ranges.length - 1]![1],
      rootIds: [...new Set(roots.map((root) => root.id))],
      ids,
      source: 'ids',
    };
  }
  return {
    startLine: 1,
    endLine: lines.length,
    rootIds: [],
    ids,
    source: 'full-document',
  };
}

/**
 * Node ids an instruction actually refers to.
 *
 * Filtered against ids present in the document so ordinary prose that happens
 * to match the id shape (`Suggested`, `constraint`) doesn't create phantom
 * conflicts that serialize unrelated edits.
 */
export function targetIds(
  instruction: string,
  session: LexicalSession
): Set<string> {
  const candidates = instruction.match(ID_PATTERN);
  if (!candidates) return new Set();
  const { byId } = indexXmlRanges(serializeWithXml(session));
  return new Set(candidates.filter((id) => byId.has(id)));
}

/** Lines of context to show a writer around its target region. Generous on
 *  purpose: a roomy window means the writer rarely has to call `readDocument`. */
const MIN_WINDOW_LINES = 20;

function xmlWindow(
  xml: string,
  range: ContextRange,
  padding = 2,
  minLines = MIN_WINDOW_LINES
): string {
  const numbered = numberLines(xml).split('\n');
  let lo = Math.max(0, range.startLine - 1 - padding);
  let hi = Math.min(numbered.length - 1, range.endLine - 1 + padding);
  // Grow symmetrically until we show at least `minLines` (or hit the doc edges).
  while (hi - lo + 1 < minLines && (lo > 0 || hi < numbered.length - 1)) {
    if (lo > 0) lo--;
    if (hi < numbered.length - 1) hi++;
  }
  return numbered.slice(lo, hi + 1).join('\n');
}

export type Writer = {
  doc: Doc;
  awarenessSource: AwarenessSource;
  release: () => void;
};

/** Per-edit timing recorded by dispatch: the writer's window and when each of
 *  its `runCode` calls executed. */
export type DispatchEditTrace = {
  /** Set when this edit was launched from onInputAvailable, before execute ran.
   *  Epoch ms. */
  streamedAt?: number;
  coderStartedAt: number;
  coderFinishedAt: number;
  runCodeAt: number[];
  /** Reply text per runCode call, positionally aligned with `runCodeAt`. */
  runCodeResults: string[];
};

/** One runCode invocation as recorded for the trace: the code plus any content
 *  the writer composed and passed alongside it. */
export type CoderRunCode = {
  code: string;
  snippets?: Record<string, string>;
  /** The reply this call produced, as the coder saw it. */
  result?: string;
};

export type DispatchToolOptions = {
  session: LexicalSession;
  /** Called once per dispatched coder so each gets its own model with private
   *  fallback state, instead of racing a shared instance. */
  makeChildModel: () => LanguageModel;
  tracker: TokenTracker;
  /** The user's original edit request, shown to every writer for tone/intent. */
  request?: string;
  runner: RunCodeToolOptions['runner'];
  params?: DocumentOpQueueParams;
  typingAnimations?: boolean;
  sleep?: (ms: number) => Promise<void>;
  signal?: AbortSignal;
  makeWriter: () => Promise<Writer>;
  /** Per-coder step cap, forwarded to every coder this tool spawns. */
  maxCoderSteps?: number;
  runTask: typeof coder;
  serialize?: (session: LexicalSession) => string;
  onOps?: RunCodeToolOptions['onOps'];
  /** Called after each dispatch call with the coder's runCode calls. */
  onCoderResult?: (codes: CoderRunCode[]) => void;
  /** Called after each dispatch call with the edit's timing trace. */
  onEditTrace?: (edit: DispatchEditTrace) => void;
  /** Resolves the parent for each `edit.dispatch` span at launch time — the
   *  supervisor turn that issued the call. Passed explicitly, and as a
   *  function, because coders launch from AI SDK stream callbacks: the
   *  ambient context is not trustworthy there, and the parent changes
   *  from one turn to the next. */
  parentSpan?: () => Span | undefined;
};

export const DispatchEditSchema = z.object({
  editing_instruction: z
    .string()
    .describe(
      'the changes you want applied to the document. writers see the user request and compose content themselves — describe the structural change and any shape/length constraints; include exact strings (quotes, ids, user-supplied text) verbatim when the writer must use them character-for-character'
    ),
});

export type DispatchEdit = z.infer<typeof DispatchEditSchema>;

export function createDispatchTool(opts: DispatchToolOptions) {
  const {
    session,
    makeChildModel,
    tracker,
    request,
    params,
    typingAnimations,
    sleep,
    signal,
    makeWriter,
    maxCoderSteps,
    runTask,
    runner,
    onOps,
    onCoderResult,
    onEditTrace,
  } = opts;
  const serialize = opts.serialize ?? serializeWithXml;

  type CoderRun = Awaited<ReturnType<typeof runTask>>;
  type EditRun = {
    run: Promise<CoderRun>;
    trace: DispatchEditTrace;
    /** This coder's own model, kept for usage attribution after it finishes. */
    model: LanguageModel;
  };
  // Coders already started from onInputAvailable, keyed by tool call id.
  const calls = new Map<string, EditRun>();

  /**
   * Node ids each in-flight coder is working on, plus a promise that settles
   * when it finishes. Parallel coders share one `LexicalSession`, so two
   * dispatches aimed at the same node interleave their edits on the same
   * subtree — the largest failure class in the trace corpus, and the one that
   * produces silently corrupted documents rather than clean failures.
   */
  const inFlight: { ids: Set<string>; done: Promise<unknown> }[] = [];

  /** Wait out any in-flight coder whose target ids overlap this instruction's.
   *
   *  Independent edits still run fully in parallel; only the ones that would
   *  collide are serialized, so this costs latency exactly where the
   *  alternative is corruption. */
  async function awaitConflicts(ids: Set<string>): Promise<void> {
    if (ids.size === 0) return;
    const blockers = inFlight
      .filter((entry) => [...ids].some((id) => entry.ids.has(id)))
      .map((entry) => entry.done);
    if (blockers.length > 0) await Promise.allSettled(blockers);
  }

  async function runEdit(
    edit: DispatchEdit,
    trace: DispatchEditTrace,
    childModel: LanguageModel,
    span: Span
  ): Promise<CoderRun> {
    // Hold off until nothing conflicting is running, THEN serialize the
    // document — so this coder's window reflects the conflicting edit rather
    // than a snapshot taken before it landed.
    await awaitConflicts(targetIds(edit.editing_instruction, session));
    try {
      // Serialized at launch time so an edit launched early sees whatever earlier
      // coders have already applied.
      const xml = serializeWithXml(session);
      const range = computeContextRange(xml, edit.editing_instruction);
      const context = xmlWindow(xml, range);
      span.setAttr('context.source', range.source);
      span.setAttr('context.lines', range.endLine - range.startLine + 1);
      const borrowStartedAt = Date.now();
      const writer = await makeWriter();
      span.setAttr('writer.wait_ms', Date.now() - borrowStartedAt);
      const { doc, awarenessSource } = writer;
      try {
        const result = await runTask(
          session,
          edit.editing_instruction,
          childModel,
          {
            doc,
            awarenessSource,
            context,
            maxSteps: maxCoderSteps,
            request,
            params,
            typingAnimations,
            sleep,
            signal,
            runner,
            onOps,
            onRunCode: () => trace.runCodeAt.push(Date.now()),
            onRunCodeResult: (result) => trace.runCodeResults.push(result),
            span,
          }
        );
        span.setAttr(
          'gen_ai.request.model',
          (childModel as { modelId: string }).modelId
        );
        span.setAttr('run_code.count', trace.runCodeAt.length);
        span.setAttr('coder.blocked', findBlocked(result) !== null);
        return result;
      } finally {
        trace.coderFinishedAt = Date.now();
        writer.release();
      }
    } catch (e) {
      span.error(e);
      throw e;
    } finally {
      span.end();
    }
  }

  /** Start the edit if it isn't already running; return its run either way. */
  function ensureLaunched(
    toolCallId: string,
    edit: DispatchEdit,
    streamed: boolean
  ): EditRun {
    const existing = calls.get(toolCallId);
    if (existing) return existing;
    const trace: DispatchEditTrace = {
      streamedAt: streamed ? Date.now() : undefined,
      coderStartedAt: Date.now(),
      coderFinishedAt: 0,
      runCodeAt: [],
      runCodeResults: [],
    };
    // runEdit ends the span in its finally, so streamed runs that reject
    // before `execute` joins them still close it.
    const parent = opts.parentSpan?.();
    const span = parent
      ? parent.span('edit.dispatch')
      : Telemetry.span('edit.dispatch');
    span.setAttr('dispatch.tool_call_id', toolCallId);
    span.setAttr('dispatch.streamed', streamed);
    span.setAttr('instruction.chars', edit.editing_instruction.length);
    const model = makeChildModel();
    const entry: EditRun = {
      run: runEdit(edit, trace, model, span),
      trace,
      model,
    };
    // A streamed run can reject before `execute` awaits it; keep that rejection
    // for the join instead of letting it escape as an unhandled rejection.
    entry.run.catch(() => {});

    // Publish this coder's targets before it starts so a later dispatch in the
    // same batch can see the conflict. Ids are resolved against the document as
    // it stands now, which is what a concurrent sibling would collide with.
    const claimed =
      typeof edit.editing_instruction === 'string'
        ? targetIds(edit.editing_instruction, session)
        : new Set<string>();
    const record = { ids: claimed, done: entry.run };
    inFlight.push(record);
    void entry.run.finally(() => {
      const i = inFlight.indexOf(record);
      if (i !== -1) inFlight.splice(i, 1);
    });

    calls.set(toolCallId, entry);
    return entry;
  }

  return {
    tool: tool({
      description:
        'spawn a writer for one edit instruction; call in parallel for independent edits',
      inputSchema: DispatchEditSchema,
      onInputAvailable: ({ input, toolCallId }) => {
        ensureLaunched(toolCallId, input, true);
      },
      execute: async (edit, { toolCallId }) => {
        const entry = ensureLaunched(toolCallId, edit, false);
        calls.delete(toolCallId);
        const result = await entry.run;
        onEditTrace?.(entry.trace);
        tracker.add(entry.model as { modelId: string }, result.totalUsage);
        const blocked = findBlocked(result);
        const summary = blocked
          ? `⚠ BLOCKED -- ${blocked.message}.`
          : `✓ APPLIED`;
        if (onCoderResult) {
          const codes = result.steps
            .flatMap((step) => step.toolCalls)
            // Schema-rejected calls never ran and carry the model's raw input.
            .filter((call) => call.toolName === 'runCode' && !call.invalid)
            .map((call, i) => {
              const input = call.input as {
                code: string;
                snippets?: SnippetPair[];
              };
              return {
                code: input.code,
                snippets: snippetsToRecord(input.snippets),
                result: entry.trace.runCodeResults[i],
              };
            });
          onCoderResult(codes);
        }
        return `${summary}\n\n<document>\n${serialize(session)}\n</document>`;
      },
    }),
  };
}

export type DispatchTool = ReturnType<typeof createDispatchTool>;