Skip to content

3D engine that AI agents drive

4.3 KB
Raw Blame
/**
 * Wording for the agent errors that recorded runs hit most. The session errors alone were a third of all tool errors
 * (21 of 68): an agent used an ID it invented, or one from a scene that was disposed or never created.
 *
 * `openSessionIds` lists the open scenes from least to most recently used; `evictedSessionIds` lists scenes the server
 * closed to stay under its scene cap.
 */
export function sessionProblem(requestedSessionId, activeSessionId, { openSessionIds = [], evictedSessionIds = [], evictionReasons = {} } = {}) {
  if (evictedSessionIds.includes(requestedSessionId)) {
    const open = openSessionIds.length ? ` Open scenes: ${openSessionIds.join(', ')}.` : '';
    const reason = evictionReasons[requestedSessionId] ?? 'the server keeps a limited number of open scenes and closes the least recently used one when a new scene is created';
    return `sessionId ${requestedSessionId} was evicted: ${reason}.${open} Pass the sessionId of an open scene, or call scene_create again (scene_export_recipe saves a scene before it is evicted).`;
  }
  if (!activeSessionId) {
    return 'No scene is active: it was never created, was disposed, or scene_create failed. Call scene_create or scene_create_asset first, then pass the sessionId it returns.';
  }
  if (openSessionIds.length > 1) {
    return `Unknown scene session ${requestedSessionId}. Open scenes: ${openSessionIds.join(', ')}; the last used is ${activeSessionId}. Pass one of them as sessionId, leave sessionId out for the last used scene, or call scene_create for a new scene.`;
  }
  return `Unknown scene session ${requestedSessionId}. The active session is ${activeSessionId}; leave sessionId out or pass that one, or call scene_dispose and then scene_create for a new scene.`;
}

/** How many scenes one server keeps open, and the resident geometry bytes they may hold together. */
export const SCENE_STORE_LIMITS = Object.freeze({ maxOpenScenes: 4, maxOpenSceneBytes: 96 * 1024 * 1024 });

function mebibytes(bytes) {
  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
}

/**
 * Which open scenes a new scene closes, and why. `openScenes` lists `{ sessionId, bytes }` from least to most recently used and
 * `incomingBytes` is the new scene's resident geometry. Scenes close oldest first until both caps hold, so a scene is only closed
 * for a cap that is really exceeded: the scene count, or the resident geometry the open scenes hold together with the new one.
 * The reason names that cap and the numbers, because "up to 4 scenes" is easy to read as a promise a few large scenes cannot keep.
 */
export function planSceneEviction(openScenes, incomingBytes, limits = SCENE_STORE_LIMITS) {
  let remainingCount = openScenes.length;
  let remainingBytes = incomingBytes + openScenes.reduce((total, scene) => total + scene.bytes, 0);
  const startingBytes = remainingBytes;
  const sessionIds = [];
  let closedForCount = false;
  let closedForBytes = false;
  for (const scene of openScenes) {
    const overCount = remainingCount + 1 > limits.maxOpenScenes;
    const overBytes = remainingBytes > limits.maxOpenSceneBytes;
    if (!overCount && !overBytes) break;
    closedForCount ||= overCount;
    closedForBytes ||= overBytes;
    remainingCount -= 1;
    remainingBytes -= scene.bytes;
    sessionIds.push(scene.sessionId);
  }
  if (!sessionIds.length) return { sessionIds, reason: null };
  const reasons = [];
  if (closedForCount) reasons.push(`the server keeps at most ${limits.maxOpenScenes} open scenes`);
  if (closedForBytes) {
    reasons.push(`the open scenes and the new one held ${mebibytes(startingBytes)} of resident geometry, over the ${mebibytes(limits.maxOpenSceneBytes)} cap (the new scene alone is ${mebibytes(incomingBytes)})`);
  }
  return { sessionIds, reason: `closed the least recently used scene${sessionIds.length > 1 ? 's' : ''} because ${reasons.join(' and ')}` };
}

/** A request made against an old revision: names both revisions, so the caller retries with the current one instead of guessing. */
export function staleRevisionMessage(subject, expectedRevision, currentRevision) {
  return `Stale revision for ${subject}: expectedRevision ${expectedRevision} is not the current revision ${currentRevision}. Pass expectedRevision ${currentRevision}; a failed scene_apply leaves the revision unchanged, and scene_inspect returns the current one.`;
}