Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
16.1 KB
Raw Blame
/**
 * Steering: a prompt the user sends while the agent is still working.
 *
 * The engine takes such a prompt at once and hands it to the model at the
 * agent's next step (after the tool or sub-agent that is running), inside the
 * running turn. Nothing here holds or refuses a prompt: `classify` only tells
 * the capture whether the prompt opens a new turn (a start snapshot, a new
 * baseline) or steers the running one (no snapshot: the turn keeps the
 * workspace its first prompt found), and `describe` finds the engine's record
 * of the steer afterwards for the trace's `turn.steer` event.
 *
 * Reads are small and bounded: the status map, then at most a few of the
 * newest messages of one session. Any failure answers "not a steer", so the
 * prompt is captured as a turn of its own, as before steering existed.
 *
 * The same rules as omnirush-cli's src/turn-steer.js (docs/turns-and-steering.md there).
 */
import { loopbackFetch } from "./server-fetch.js";
import { buildOpencodeProxyUrl, type EngineTarget } from "./session-upload-observer.js";

const NORMAL_FINISH = new Set(["stop", "end_turn", "end-turn", "stop_sequence", "length"]);
const STATUS_MAX_BYTES = 1024 * 1024;
const MESSAGES_MAX_BYTES = 16 * 1024 * 1024;

type Json = Record<string, unknown>;

const isRecord = (value: unknown): value is Json => value !== null && typeof value === "object" && !Array.isArray(value);
const infoOf = (message: unknown): unknown => (isRecord(message) && isRecord(message.info) ? message.info : message);
const toMs = (value: unknown): number | null => (typeof value === "number" && Number.isFinite(value) ? value : null);

/** Why a prompt counted as it did: a steer (`working`, `busy_unread`) or a turn start (the rest). */
export type SteerReason = "idle" | "working" | "busy_unread" | "not_started" | "ending" | "compacting" | "status_unreadable";
export type SteerVerdict = { steer: boolean; busy: boolean | null; reason: SteerReason; error?: string };

/** A tool call relative to a steer: `sub_agent` is the task tool's child session. */
export type SteerToolCall = { tool: string | null; call_id: string | null; started_at: string; ended_at?: string; sub_agent?: string };
export type SteerFound = { message_id: string; created_at: string; running: SteerToolCall[]; after_call: SteerToolCall | null };

function isPrompt(message: unknown): boolean {
  const info = infoOf(message);
  if (!isRecord(info) || info.role !== "user" || info.agent === "compaction") return false;
  const parts = (isRecord(message) && Array.isArray(message.parts) ? message.parts : []).filter(isRecord);
  if (parts.some((part) => part.type === "compaction")) return false;
  const content = parts.filter((part) => ["text", "file", "agent", "subtask"].includes(String(part.type)));
  return !(content.length > 0 && content.every((part) => part.type === "text" && part.synthetic === true));
}

/** A compaction's summary (the engine compacting the chat): no agent step, a prompt sent then opens a turn. */
export function compactionSummary(message: unknown): boolean {
  const info = infoOf(message);
  return isRecord(info) && info.role === "assistant" && (info.summary === true || info.mode === "compaction" || info.agent === "compaction");
}

/** Whether the agent is mid-turn on `newest` (the session's newest message): an assistant step that has not ended normally. */
export function workingOn(newest: unknown): boolean {
  const info = infoOf(newest);
  if (!isRecord(info) || info.role !== "assistant") return false;
  if (info.error != null || compactionSummary(newest)) return false;
  const completed = toMs(isRecord(info.time) ? info.time.completed : undefined);
  return !(completed !== null && typeof info.finish === "string" && NORMAL_FINISH.has(info.finish));
}

/** The tool calls of `messages` relative to `at`: the ones running then and the last one started by then. */
export function toolsAround(messages: readonly unknown[], at: number): { running: SteerToolCall[]; last: SteerToolCall | null } {
  const running: SteerToolCall[] = [];
  let last: SteerToolCall | null = null;
  let lastStart = -Infinity;
  for (const message of messages) {
    const info = infoOf(message);
    if (!isRecord(info) || info.role !== "assistant") continue;
    for (const part of isRecord(message) && Array.isArray(message.parts) ? message.parts : []) {
      if (!isRecord(part) || part.type !== "tool") continue;
      const state = isRecord(part.state) ? part.state : {};
      const time = isRecord(state.time) ? state.time : {};
      const start = toMs(time.start);
      if (start === null || start > at) continue;
      const end = toMs(time.end);
      const call: SteerToolCall = {
        tool: typeof part.tool === "string" ? part.tool : null,
        call_id: typeof part.callID === "string" ? part.callID : null,
        started_at: new Date(start).toISOString(),
        ...(end !== null ? { ended_at: new Date(end).toISOString() } : {}),
      };
      const child = isRecord(state.metadata) ? state.metadata.sessionId : undefined;
      if (typeof child === "string") call.sub_agent = child;
      if (start >= lastStart) { last = call; lastStart = start; }
      if (end === null || end > at) running.push(call);
    }
  }
  return { running, last };
}

async function readBounded(response: Response, limit: number): Promise<unknown> {
  const reader = response.body?.getReader();
  if (!reader) throw new Error("empty response");
  const chunks: Uint8Array[] = [];
  let bytes = 0;
  try {
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      bytes += value.byteLength;
      if (bytes > limit) {
        await reader.cancel().catch(() => undefined);
        throw new Error("response too large");
      }
      chunks.push(value);
    }
  } finally {
    reader.releaseLock();
  }
  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
}

export type SteerTrackerOptions = {
  /** Bounds each read. */
  timeoutMs?: number;
  fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
  /** The waits before each attempt to find a steer's record. */
  delays?: readonly number[];
};

/** The v1 engine `target` (its base URL, auth header and directory scope): which prompts steer, and the record of each steer. */
export function createSteerTracker(target: EngineTarget, { timeoutMs = 1_500, fetchImpl = loopbackFetch, delays = [150, 400, 1_000, 2_500, 5_000] }: SteerTrackerOptions = {}) {
  if (target.engine === "v2") return createSteerTrackerV2(target, { timeoutMs, fetchImpl, delays });
  const read = async (route: string, query: Record<string, string>, limit: number): Promise<unknown> => {
    const url = new URL(buildOpencodeProxyUrl(target.baseUrl, route, target.search));
    for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value);
    const response = await fetchImpl(url.toString(), { headers: new Headers(target.headers), signal: AbortSignal.timeout(timeoutMs) });
    if (!response.ok) {
      await response.body?.cancel().catch(() => undefined);
      throw new Error(`engine answered ${response.status}`);
    }
    return readBounded(response, limit);
  };
  const newest = async (sessionId: string, count: number): Promise<unknown[]> => {
    const list = await read(`/session/${encodeURIComponent(sessionId)}/message`, { limit: String(count) }, MESSAGES_MAX_BYTES);
    if (!Array.isArray(list)) throw new Error("unreadable message list");
    return list;
  };

  return {
    /**
     * Whether a prompt to `sessionId`, about to be forwarded, steers a running
     * turn: the engine says the session is busy and its newest message is an
     * assistant step still at work. A session busy with nothing answered yet
     * (the prompt before was just sent) gets the two prompts answered together
     * by the engine: that is a turn of its own, as the converter counts it.
     */
    async classify(sessionId: string): Promise<SteerVerdict> {
      let statuses: unknown;
      try { statuses = await read("/session/status", {}, STATUS_MAX_BYTES); }
      catch (error) { return { steer: false, busy: null, reason: "status_unreadable", error: errorText(error) }; }
      const entry = isRecord(statuses) ? statuses[sessionId] : undefined;
      const type = isRecord(entry) ? entry.type : "idle";
      if (type !== "busy" && type !== "retry") return { steer: false, busy: false, reason: "idle" };
      try {
        const [last] = (await newest(sessionId, 1)).slice(-1);
        if (workingOn(last)) return { steer: true, busy: true, reason: "working" };
        if (compactionSummary(last)) return { steer: false, busy: true, reason: "compacting" };
        const info = infoOf(last);
        return { steer: false, busy: true, reason: isRecord(info) && info.role === "user" ? "not_started" : "ending" };
      } catch (error) {
        // Busy, newest unknown: the engine delivers the prompt into the running turn.
        return { steer: true, busy: true, reason: "busy_unread", error: errorText(error) };
      }
    },

    /**
     * The engine's record of a steer sent at `sentAt`: its message id and
     * creation time, the tool calls running when it arrived and the last one
     * started before it. Null when it cannot be found in time.
     */
    async describe(sessionId: string, sentAt: number, { known = new Set<string>(), stopped = () => false }: { known?: ReadonlySet<string>; stopped?: () => boolean } = {}): Promise<SteerFound | null> {
      for (const delay of delays) {
        await new Promise<void>((resolve) => { const timer = setTimeout(resolve, delay); timer.unref?.(); });
        if (stopped()) return null;
        let list: unknown[];
        try { list = await newest(sessionId, 6); } catch { continue; }
        // The first prompt the engine created since it was sent (the engine creates it on receipt).
        const steer = list.find((message) => {
          const info = infoOf(message);
          if (!isRecord(info)) return false;
          const created = toMs(isRecord(info.time) ? info.time.created : undefined);
          return isPrompt(message) && typeof info.id === "string" && !known.has(info.id) && created !== null && created >= sentAt - 50;
        });
        if (!steer) continue;
        const info = infoOf(steer) as Json;
        const created = toMs((info.time as Json).created) as number;
        const before = list.filter((message) => {
          const at = (() => { const i = infoOf(message); return isRecord(i) && isRecord(i.time) ? toMs(i.time.created) : null; })();
          return at !== null && at <= created;
        });
        const { running, last } = toolsAround(before, created);
        return { message_id: info.id as string, created_at: new Date(created).toISOString(), running, after_call: last };
      }
      return null;
    },
  };
}

/**
 * The same on the 2.x engine (the CLI's createSteerTrackerV2): it steers natively (a prompt to a
 * running session is delivered into its turn), so a prompt to a session the engine lists as running
 * steers once its turn answered anything. The record is the 2.x user message; tools are `content` items.
 */
function createSteerTrackerV2(target: EngineTarget, { timeoutMs, fetchImpl, delays }: Required<Pick<SteerTrackerOptions, "timeoutMs" | "fetchImpl" | "delays">>) {
  const read = async (route: string, limit: number): Promise<unknown> => {
    const response = await fetchImpl(buildOpencodeProxyUrl(target.baseUrl, route, target.search), { headers: new Headers(target.headers), signal: AbortSignal.timeout(timeoutMs) });
    if (!response.ok) {
      await response.body?.cancel().catch(() => undefined);
      throw new Error(`engine answered ${response.status}`);
    }
    const body = await readBounded(response, limit);
    return isRecord(body) ? body.data : null;
  };
  const newest = async (sessionId: string, count: number): Promise<Json[]> => {
    const list = await read(`/api/session/${encodeURIComponent(sessionId)}/message?order=desc&limit=${count}`, MESSAGES_MAX_BYTES);
    if (!Array.isArray(list)) throw new Error("unreadable message list");
    return list.filter(isRecord).reverse();
  };
  const tools = (message: Json): Json[] => (Array.isArray(message.content) ? message.content.filter((item): item is Json => isRecord(item) && item.type === "tool") : []);
  return {
    async classify(sessionId: string): Promise<SteerVerdict> {
      let active: unknown;
      try { active = await read("/api/session/active", STATUS_MAX_BYTES); }
      catch (error) { return { steer: false, busy: null, reason: "status_unreadable", error: errorText(error) }; }
      if (!isRecord(active) || !(sessionId in active)) return { steer: false, busy: false, reason: "idle" };
      try {
        const [last] = (await newest(sessionId, 1)).slice(-1);
        if (last?.type === "assistant") return { steer: true, busy: true, reason: "working" };
        if (last?.type === "compaction") return { steer: false, busy: true, reason: "compacting" };
        return { steer: false, busy: true, reason: last?.type === "user" ? "not_started" : "ending" };
      } catch (error) {
        return { steer: true, busy: true, reason: "busy_unread", error: errorText(error) };
      }
    },
    async describe(sessionId: string, sentAt: number, { known = new Set<string>(), stopped = () => false }: { known?: ReadonlySet<string>; stopped?: () => boolean } = {}): Promise<SteerFound | null> {
      for (const delay of delays) {
        await new Promise<void>((resolve) => { const timer = setTimeout(resolve, delay); timer.unref?.(); });
        if (stopped()) return null;
        let list: Json[];
        try { list = await newest(sessionId, 6); } catch { continue; }
        const createdOf = (message: Json) => toMs(isRecord(message.time) ? message.time.created : undefined);
        const steer = list.find((message) => message.type === "user" && typeof message.id === "string" && !known.has(message.id) && (createdOf(message) ?? -Infinity) >= sentAt - 50);
        if (!steer) continue;
        const created = createdOf(steer) as number;
        const running: SteerFound["running"] = [];
        let last: SteerFound["after_call"] = null;
        for (const item of list.flatMap(tools)) {
          const time = isRecord(item.time) ? item.time : {};
          const start = toMs(time.created);
          if (start === null || start > created) continue;
          const end = toMs(time.completed);
          const call = { tool: typeof item.name === "string" ? item.name : null, call_id: typeof item.id === "string" ? item.id : null, started_at: new Date(start).toISOString(), ...(end !== null ? { ended_at: new Date(end).toISOString() } : {}) };
          if (!last || start >= Date.parse(last.started_at)) last = call;
          if (end === null || end > created) running.push(call);
        }
        return { message_id: steer.id as string, created_at: new Date(created).toISOString(), running, after_call: last };
      }
      return null;
    },
  };
}

function errorText(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

/** The steer messages already claimed per session (a later steer's record never names an earlier one's message). */
const MAX_STEER_SESSIONS = 256;
const MAX_STEERS_PER_SESSION = 64;
const claimedSteers = new Map<string, Set<string>>();

export function claimedSteerIds(sessionId: string): Set<string> {
  let known = claimedSteers.get(sessionId);
  if (known) {
    claimedSteers.delete(sessionId);
  } else {
    known = new Set();
  }
  claimedSteers.set(sessionId, known);
  while (claimedSteers.size > MAX_STEER_SESSIONS) claimedSteers.delete(claimedSteers.keys().next().value as string);
  return known;
}

export function claimSteerId(known: Set<string>, id: string): void {
  known.add(id);
  while (known.size > MAX_STEERS_PER_SESSION) known.delete(known.values().next().value as string);
}

/**
 * The `turn.steer` record (schema 1, without `turn_started_at`, which the
 * session uploader adds): `found` from describe(), null when it was not found in time.
 */
export function steerRecord(found: SteerFound | null, sentAt: number, reason: SteerReason): Record<string, unknown> {
  return {
    message_id: found?.message_id ?? null,
    sent_at: new Date(sentAt).toISOString(),
    ...(found ? { created_at: found.created_at, running: found.running, after_call: found.after_call } : {}),
    delivery: "next_step",
    classified: reason,
  };
}