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.9 KB
Raw Blame
/**
 * The session log over GraphQL, through the normalized cache.
 *
 * `cache-and-network` answers twice: from disk when the cache holds the log,
 * then from the network, which the exchange writes back. The caller hears
 * both in order. A watch that follows the session subscribes to its appended
 * frames before the query goes out, so no row between the two is lost, and
 * appends what the subscription delivers to the cached list, so the next
 * open starts from a log as complete as the last one ended.
 */

import {
  traceCacheWrite,
  traceFollowResumed,
} from '@core/agent-session/load-telemetry';
import {
  enableGraphqlSoup,
  isFeatureEnabled,
} from '@core/constant/featureFlags';
import { normalizedCacheResultMetadata } from '@graphql-cache/exchange/normalized-cache-exchange';
import type {
  AgentSessionLogEntryDto,
  LogDirectionDto,
  SessionBot,
} from '@service-agent-harness/generated/schemas';
import {
  AgentSessionLogAppendedDocument,
  type AgentSessionLogAppendedSubscription,
  type AgentSessionLogAppendedSubscriptionVariables,
  AgentSessionLogDocument,
  type AgentSessionLogQuery,
  type AgentSessionLogQueryVariables,
} from '@service-storage/graphql/generated/graphql';
import {
  getGraphqlCacheHost,
  getGraphqlSoupClient,
} from '@service-storage/graphql-soup';
import { type OperationResult, stringifyDocument } from '@urql/core';
import { onEnd, pipe, subscribe } from 'wonka';

/** What the fold needs: the agent and the raw rows. */
export type SessionLogSnapshot = {
  bot: SessionBot;
  rows: AgentSessionLogEntryDto[];
};

/**
 * The log could not be served. `reason` separates a session the viewer
 * cannot see (or that does not exist) from a transport failure that a
 * retry could fix.
 */
export class AgentSessionLogUnavailable extends Error {
  constructor(
    readonly sessionId: string,
    readonly reason: 'inaccessible' | 'failed',
    options?: ErrorOptions
  ) {
    super(`agent session log is ${reason}: ${sessionId}`, options);
    this.name = 'AgentSessionLogUnavailable';
  }
}

/** Why {@link SessionLogWatch.cached} came back empty. */
export type CacheMiss =
  /** No persistent cache in this client, or it was disabled. */
  | 'no_cache'
  /** The watch asked for the network only. */
  | 'network_only'
  /** The network answered before the cache read hit, or the read missed. */
  | 'network_first'
  /** The cache answered without this session's log, or with an error. */
  | 'empty'
  /** The cached log could not be read into rows. */
  | 'unreadable'
  /** The watch stopped first. */
  | 'stopped';

export type SessionLogWatch = {
  /**
   * The log as the cache last held it, or nothing when the cache has no
   * copy or the network answered first. Never rejects.
   */
  cached: Promise<SessionLogSnapshot | undefined>;
  /** Why `cached` resolved to nothing, once it has; for telemetry. */
  cacheMiss: () => CacheMiss | undefined;
  /** The log as the server holds it now. Rejects with {@link AgentSessionLogUnavailable}. */
  fetched: Promise<SessionLogSnapshot>;
  /**
   * Stop listening. Unsettled promises settle as a miss and a failure; a
   * follow is unsubscribed and what it still owes the cache is written.
   */
  stop: () => void;
};

/**
 * How a watch follows the session after the fetch: each run of frames the
 * harness appends, in log order, as the harness flushed it. `gap` means
 * rows may have been missed - the subscription ended and was reopened, or a
 * run could not be read - and the caller must refetch the log.
 */
export type SessionLogFollow = {
  rows: (rows: AgentSessionLogEntryDto[]) => void;
  gap: () => void;
};

/**
 * Whether a watch can follow the session over GraphQL. Only the client
 * built with the Soup websocket carries subscriptions; without it, live
 * rows still arrive through the connection gateway.
 */
export function canFollowAgentSessionLog(): boolean {
  return isFeatureEnabled(enableGraphqlSoup);
}

const DIRECTIONS: ReadonlySet<string> = new Set<LogDirectionDto>([
  'to_server',
  'to_runtime',
  'notification',
]);

function isDirection(value: string): value is LogDirectionDto {
  return DIRECTIONS.has(value);
}

type LogData = NonNullable<AgentSessionLogQuery['user']['agentSession']>['log'];
type LogEntry = LogData['entries'][number];

/** One GraphQL entry in the wire shape the fold reads. */
function toRow(sessionId: string, entry: LogEntry): AgentSessionLogEntryDto {
  if (!isDirection(entry.direction)) {
    throw new AgentSessionLogUnavailable(sessionId, 'failed', {
      cause: new Error(`unknown log direction: ${entry.direction}`),
    });
  }
  return {
    id: entry.id,
    createdAt: entry.createdAt,
    ...(entry.userId === null ? {} : { userId: entry.userId }),
    direction: entry.direction,
    content: entry.content as AgentSessionLogEntryDto['content'],
  };
}

/** The wire shape the fold reads, from the GraphQL selection. */
function toSnapshot(sessionId: string, log: LogData): SessionLogSnapshot {
  return {
    bot: {
      id: log.bot.id,
      name: log.bot.name,
      handle: log.bot.handle,
      ...(log.bot.avatarUrl === null ? {} : { avatarUrl: log.bot.avatarUrl }),
    },
    rows: log.entries.map((entry) => toRow(sessionId, entry)),
  };
}

/** How long appended rows wait for company before they are written. */
const CACHE_WRITE_DEBOUNCE_MS = 1_000;

/**
 * Watch one session's log: the cached copy first when there is one, then
 * the fetched one. `policy` `network-only` skips the cache read, for a
 * resync that wants only what the server holds. With `follow`, the watch
 * also subscribes to the session's appended frames, before the query so
 * the two overlap rather than leave a hole, and hands each run on.
 */
export function watchAgentSessionLog(
  sessionId: string,
  policy: 'cache-and-network' | 'network-only' = 'cache-and-network',
  follow?: SessionLogFollow
): SessionLogWatch {
  let resolveCached!: (snapshot: SessionLogSnapshot | undefined) => void;
  let cacheSettled = false;
  let cacheMiss: CacheMiss | undefined;
  let cacheAnsweredEmpty = false;
  const hitCache = (snapshot: SessionLogSnapshot) => {
    if (cacheSettled) return;
    cacheSettled = true;
    resolveCached(snapshot);
  };
  const missCache = (reason: CacheMiss) => {
    if (cacheSettled) return;
    cacheSettled = true;
    cacheMiss = reason;
    resolveCached(undefined);
  };
  let resolveFetched!: (snapshot: SessionLogSnapshot) => void;
  let rejectFetched!: (error: AgentSessionLogUnavailable) => void;
  const cached = new Promise<SessionLogSnapshot | undefined>((resolve) => {
    resolveCached = resolve;
  });
  const fetched = new Promise<SessionLogSnapshot>((resolve, reject) => {
    resolveFetched = resolve;
    rejectFetched = reject;
  });
  // A rejection nobody has awaited yet must not be reported as unhandled.
  fetched.catch(() => undefined);

  const appender = follow ? createAppender(sessionId) : undefined;
  const unsubscribeFollow = follow
    ? followAppended(sessionId, follow, appender)
    : () => undefined;

  const settleFetched = (result: OperationResult<AgentSessionLogQuery>) => {
    missCache(
      policy === 'network-only'
        ? 'network_only'
        : !getGraphqlCacheHost()
          ? 'no_cache'
          : cacheAnsweredEmpty
            ? 'empty'
            : 'network_first'
    );
    if (result.error) {
      rejectFetched(
        new AgentSessionLogUnavailable(sessionId, 'failed', {
          cause: result.error,
        })
      );
      return;
    }
    const log = result.data?.user.agentSession?.log;
    if (!log) {
      rejectFetched(new AgentSessionLogUnavailable(sessionId, 'inaccessible'));
      return;
    }
    try {
      const snapshot = toSnapshot(sessionId, log);
      appender?.fetched(snapshot.rows);
      resolveFetched(snapshot);
    } catch (error) {
      rejectFetched(
        error instanceof AgentSessionLogUnavailable
          ? error
          : new AgentSessionLogUnavailable(sessionId, 'failed', {
              cause: error,
            })
      );
    }
  };

  const { unsubscribe } = pipe(
    getGraphqlSoupClient().query<
      AgentSessionLogQuery,
      AgentSessionLogQueryVariables
    >(AgentSessionLogDocument, { sessionId }, { requestPolicy: policy }),
    subscribe((result) => {
      const source = normalizedCacheResultMetadata(result)?.source;
      const fromCache =
        source === 'normalized-cache-hit' ||
        source === 'affected-cache-reread' ||
        result.stale;
      if (fromCache) {
        const log = result.data?.user.agentSession?.log;
        // A cached miss or a cached refusal is not worth folding; the
        // network answer settles both.
        if (log && !result.error) {
          try {
            hitCache(toSnapshot(sessionId, log));
          } catch {
            missCache('unreadable');
          }
        } else {
          cacheAnsweredEmpty = true;
        }
        return;
      }
      settleFetched(result);
      unsubscribe();
    })
  );

  return {
    cached,
    cacheMiss: () => cacheMiss,
    fetched,
    stop: () => {
      unsubscribe();
      unsubscribeFollow();
      appender?.flush();
      missCache('stopped');
      rejectFetched(new AgentSessionLogUnavailable(sessionId, 'failed'));
    },
  };
}

/**
 * Waits before reopening a subscription that ended, by how many times in a
 * row it has: the first reopens at once, for a server that closed a
 * subscriber which fell behind; the rest back off, for one that keeps
 * refusing.
 */
const RESUBSCRIBE_DELAYS_MS = [0, 1_000, 3_000, 10_000, 30_000];

/**
 * Subscribe to the session's appended frames. Every run reaches `follow`
 * at once; the appender hears it too, to keep the cached log in step.
 *
 * A subscription that ends - an error, or the server completing it - is
 * reopened, and then reported as a gap: the rows it dropped are only in the
 * durable log, and the refetch starts after the new subscription so the two
 * overlap. Left ended, the session would hear nothing more until it was
 * opened again, and a control the runtime answered would wait on a reread.
 */
function followAppended(
  sessionId: string,
  follow: SessionLogFollow,
  appender: Appender | undefined
): () => void {
  let stopped = false;
  let failures = 0;
  let unsubscribe: (() => void) | undefined;
  let reopen: ReturnType<typeof setTimeout> | undefined;

  const open = () => {
    let ended = false;
    const end = (reason: 'error' | 'ended') => {
      if (ended || stopped) return;
      ended = true;
      const delay =
        RESUBSCRIBE_DELAYS_MS[
          Math.min(failures, RESUBSCRIBE_DELAYS_MS.length - 1)
        ];
      failures += 1;
      traceFollowResumed(sessionId, reason, failures, delay);
      // Reopened from a timer, never inside the ending source's own callback.
      reopen = setTimeout(() => {
        reopen = undefined;
        unsubscribe?.();
        if (stopped) return;
        open();
        follow.gap();
      }, delay);
    };
    ({ unsubscribe } = pipe(
      getGraphqlSoupClient().subscription<
        AgentSessionLogAppendedSubscription,
        AgentSessionLogAppendedSubscriptionVariables
      >(AgentSessionLogAppendedDocument, { sessionId }),
      onEnd(() => end('ended')),
      subscribe((result) => {
        if (ended) return;
        if (result.error) {
          console.warn(
            '[agent-session] log subscription interrupted',
            result.error
          );
          end('error');
          return;
        }
        const entries = result.data?.agentSessionLogAppended;
        if (!entries || entries.length === 0) return;
        failures = 0;
        let rows: AgentSessionLogEntryDto[];
        try {
          rows = entries.map((entry) => toRow(sessionId, entry));
        } catch (error) {
          console.warn(
            '[agent-session] log subscription row unreadable',
            error
          );
          follow.gap();
          return;
        }
        appender?.appended(rows);
        follow.rows(rows);
      })
    ));
  };
  open();

  return () => {
    stopped = true;
    clearTimeout(reopen);
    unsubscribe?.();
  };
}

type Appender = {
  /** The fetched log landed in the cache; rows held until now go after it. */
  fetched: (rows: AgentSessionLogEntryDto[]) => void;
  /** The subscription delivered a run. */
  appended: (rows: AgentSessionLogEntryDto[]) => void;
  /** Write now what a pending timer would have. */
  flush: () => void;
};

/**
 * Keep the cached log in step with what the subscription delivered, once
 * the fetched log is what the cache holds. The exchange writes each fetched
 * snapshot itself; only rows after one need appending. Rows that arrive
 * before the fetch settles wait: written earlier, the fetched write would
 * replace the list without them. Dedupes by row id, as the fold does, so a
 * row delivered twice is stored once.
 */
function createAppender(sessionId: string): Appender {
  let known: Set<string> | undefined;
  let pending: AgentSessionLogEntryDto[] = [];
  let timer: ReturnType<typeof setTimeout> | undefined;

  const write = () => {
    const rows = pending;
    if (rows.length === 0) return;
    pending = [];
    const startedAt = performance.now();
    void appendAgentSessionLogRows(sessionId, rows).then(
      () => traceCacheWrite(sessionId, startedAt, rows.length),
      (error: unknown) => {
        console.warn('[agent-session] log rows could not be cached', error);
      }
    );
  };
  const schedule = () => {
    if (timer !== undefined) return;
    timer = setTimeout(() => {
      timer = undefined;
      write();
    }, CACHE_WRITE_DEBOUNCE_MS);
  };
  const remember = (rows: AgentSessionLogEntryDto[]) => {
    if (!known) return false;
    let changed = false;
    for (const row of rows) {
      if (known.has(row.id)) continue;
      known.add(row.id);
      pending.push(row);
      changed = true;
    }
    return changed;
  };

  return {
    fetched(rows) {
      known = new Set(rows.map((row) => row.id));
      const held = pending;
      pending = [];
      if (remember(held)) schedule();
    },
    appended(rows) {
      if (!known) {
        pending.push(...rows);
        return;
      }
      if (remember(rows)) schedule();
    },
    flush() {
      if (timer === undefined) return;
      clearTimeout(timer);
      timer = undefined;
      write();
    },
  };
}

const LOG_QUERY = stringifyDocument(AgentSessionLogDocument);
const LOG_OPERATION = 'AgentSessionLog';

/**
 * Append rows to the cached log, so the next open folds them before the
 * network answers. A cache without this session's log has nothing to
 * extend; the next fetch writes the whole thing.
 */
async function appendAgentSessionLogRows(
  sessionId: string,
  rows: AgentSessionLogEntryDto[]
): Promise<void> {
  const host = getGraphqlCacheHost();
  if (!host || rows.length === 0) return;
  const args = {
    query: LOG_QUERY,
    operationName: LOG_OPERATION,
    variables: { sessionId } satisfies AgentSessionLogQueryVariables,
  };
  const read = await host.readQuery({ ...args, priority: 'user-visible' });
  if (read.kind !== 'hit') return;
  // The generated document defines the normalized cache result's shape.
  const data = read.data as AgentSessionLogQuery;
  const log = data.user.agentSession?.log;
  if (!log) return;
  const known = new Set(log.entries.map((entry) => entry.id));
  const appended = rows
    .filter((row) => !known.has(row.id))
    .map((row) => ({
      id: row.id,
      createdAt: row.createdAt,
      userId: row.userId ?? null,
      direction: row.direction,
      content: row.content,
    }));
  if (appended.length === 0) return;
  await host.writeQuery({
    ...args,
    data: {
      user: {
        id: data.user.id,
        agentSession: {
          id: sessionId,
          log: { bot: log.bot, entries: [...log.entries, ...appended] },
        },
      },
    } satisfies AgentSessionLogQuery,
  });
}

/** Drop the cached session so nothing renders for a viewer who was refused. */
export async function forgetAgentSessionLog(sessionId: string): Promise<void> {
  const host = getGraphqlCacheHost();
  if (!host) return;
  await host.deleteRecords([`GraphqlSoupAgentSession:${sessionId}`]);
}