Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

19.7 KB
Raw Blame
/**
 * The API tab's Try it, without React: the state of one panel, the reducer that folds a run's
 * stream into it, and the async driver that feeds it.
 *
 * A run is the Agent API's own run, sent through the owner's try route (`tryAgentApi`) and read
 * with the SDK's `readSse`, so the panel sees exactly the `data:` payloads a program would. Every
 * payload is kept verbatim: the raw view prints them back, one numbered line each. The rendered
 * view reads the same payloads as rows, one per item or event:
 *
 * - An item's fragments and its complete form are one row (`text`, `thinking`, `tool_call`,
 *   `tool_result`, `summary`, the inline media). While fragments arrive the row shows them joined;
 *   once the `.done` arrives it shows the `.done`'s content instead. The two are the same item, so
 *   nothing compares them: the latest is what shows. Fragments find their row by the item they
 *   belong to — a tool call or result by its `tool_call_id`, since results interleave — so a row
 *   keeps its place when other rows come between its fragments.
 * - Every other event is a row of its own, with its key fields.
 *
 * `run.done` gives the status strip, folded by the SDK's `RunCollector` as a program's
 * `result()` would be. The Session id that `run.started` names stays after the run, so the next
 * run continues the conversation, the way a program passes `session_id`; New conversation
 * forgets it.
 */
import { readSse, RunCollector } from "@adelie/amsp";
import type { AmspError, AmspEvent, RunRequest, RunResult, TokenCounts } from "@adelie/amsp";
import { ApiError } from "../../api/client";
import * as api from "../../api/endpoints";

/** Where a one-line value is cut, so one long argument string does not take the row. */
const CUT = 120;

const cut = (text: string): string => (text.length > CUT ? `${text.slice(0, CUT)}…` : text);

/** One value of an event row: the wire name it is known by (if any) and the value. */
export interface TryField {
  name?: string;
  value: string;
  /** Free text (a message, a list of names) rather than a value to pick out. */
  quiet?: boolean;
}

/** A row standing for one item: its fragments, its complete form, or both. */
export interface TryItemRow {
  kind: "item";
  /** The row's place in the rendered view, from 0; it never moves. */
  id: number;
  /** What the item is: its events' type before `.delta` / `.done` (`text`, `tool_call`, …). */
  item: string;
  /** The item its fragments and `.done` belong to. */
  key: string;
  /** Fragments arrived and nothing has said the item is complete yet. */
  open: boolean;
  /**
   * The content so far: the fragments joined, or the `.done`'s own once it came. A text, a
   * thinking or a summary's text; a tool call's arguments; a tool result's output.
   */
  text: string;
  /** A tool call's tool. */
  name?: string;
  /** Inline media and image inputs: what they are and how big, never the bytes themselves. */
  media?: { mime: string; bytes: number };
  /** How many images a tool result carries. */
  images?: number;
  /** What sets the item apart from the plain case: a text's sender, a stop other than completed. */
  tags: string[];
  /** The child Session chain it came from, outer→inner; absent for the main Session. */
  origin?: string;
}

/** A row standing for one event that is not part of an item. */
export interface TryEventRow {
  kind: "event";
  id: number;
  /** The event's `type`; `?` for a payload that is not an AMSP event. */
  type: string;
  fields: TryField[];
  /** On `approval.requested`: the call it asks about, and whether an answer is still open. */
  approval?: { toolCallId: string; pending: boolean };
  origin?: string;
}

export type TryRow = TryItemRow | TryEventRow;

/** The label a row carries in the rendered view: the item's kind, or the event's type. */
export const rowLabel = (row: TryRow): string => (row.kind === "item" ? row.item : row.type);

/** The kinds of item whose events merge into one row. */
const ITEMS = new Set([
  "text",
  "thinking",
  "tool_call",
  "tool_result",
  "summary",
  "inline_data",
  "inline_thinking",
  "image_url",
]);

/** The field that carries an item's text, on its fragments and on its `.done` alike. */
const TEXT_FIELD: Record<string, string> = {
  text: "text",
  thinking: "thinking",
  summary: "text",
  tool_call: "arguments",
  tool_result: "output",
};

/** The payload as an AMSP event, or null when it is not one (not JSON, or no `type`). */
function parseEvent(payload: string): AmspEvent | null {
  try {
    const value: unknown = JSON.parse(payload);
    return value !== null &&
      typeof value === "object" &&
      typeof (value as { type?: unknown }).type === "string"
      ? (value as AmspEvent)
      : null;
  } catch {
    return null;
  }
}

const str = (value: unknown): string => (typeof value === "string" ? value : "");

/** The size of base64 data once decoded. */
function base64Bytes(data: string): number {
  const body = data.replace(/[\s=]/g, "");
  return Math.floor((body.length * 3) / 4);
}

/** A `data:` URL's media type and decoded size; null for any other URL. */
function dataUrlMedia(url: string): { mime: string; bytes: number } | null {
  const match = /^data:([^;,]*)(;base64)?,/.exec(url);
  if (match === null) return null;
  const body = url.slice(match[0].length);
  return {
    mime: match[1] || "text/plain",
    bytes: match[2] !== undefined ? base64Bytes(body) : body.length,
  };
}

const originOf = (ev: AmspEvent): string | undefined =>
  ev.origin !== undefined && ev.origin.length > 0 ? ev.origin.join("/") : undefined;

/** The row an item's event belongs to, as it reads after that event. */
function itemRow(
  prev: TryItemRow | undefined,
  id: number,
  ev: AmspEvent,
  item: string,
  done: boolean,
) {
  const f = ev as unknown as Record<string, unknown>;
  const field = TEXT_FIELD[item];
  const piece = field !== undefined ? str(f[field]) : "";
  const origin = originOf(ev);
  const row: TryItemRow = prev
    ? { ...prev, tags: [...prev.tags] }
    : {
        kind: "item",
        id,
        item,
        key: itemKey(ev, item),
        open: true,
        text: "",
        tags: [],
        ...(origin !== undefined ? { origin } : {}),
      };
  // A complete item replaces whatever its fragments said; a fragment adds to it.
  row.text = done ? piece : row.text + piece;
  if (item === "tool_call") {
    const name = str(f.name);
    if (done || row.name === undefined || row.name === "") row.name = name;
  }
  // A result's images are never fragmented: whichever event carries them carries the whole set.
  if (Array.isArray(f.images)) row.images = f.images.length;
  if (item === "inline_data" || item === "inline_thinking") {
    const bytes = base64Bytes(str(f.data));
    row.media = {
      mime: str(f.mime_type) || row.media?.mime || "",
      bytes: done ? bytes : (row.media?.bytes ?? 0) + bytes,
    };
  }
  if (item === "image_url") {
    const url = str(f.image_url);
    const media = dataUrlMedia(url);
    if (media !== null) row.media = media;
    else row.text = url;
  }
  if (done) {
    row.open = false;
    // An image input is the user's by definition; elsewhere a user-role item is the exception.
    if (f.role === "user" && item !== "image_url") row.tags.push(str(f.sender) || "user");
    const stop = str(f.stop_reason);
    if (stop !== "" && stop !== "completed") row.tags.push(stop);
  }
  return row;
}

/** Which item an event belongs to: its kind, role, tool call and Session. */
function itemKey(ev: AmspEvent, item: string): string {
  const f = ev as unknown as Record<string, unknown>;
  return [item, str(f.role), str(f.tool_call_id), originOf(ev) ?? ""].join(" ");
}

const tokens = (usage: TokenCounts | null): TryField[] =>
  usage === null
    ? []
    : [
        { name: "output", value: String(usage.output) },
        { name: "total", value: String(usage.total) },
      ];

const failure = (error: AmspError | undefined): TryField[] =>
  error === undefined ? [] : [{ value: error.code }, { value: error.message, quiet: true }];

/** The key fields of an event that stands alone, in the order its row shows them. */
export function eventFields(ev: AmspEvent): TryField[] {
  switch (ev.type) {
    case "run.started":
      return [{ value: ev.session_id }];
    case "run.done":
      return [
        { value: ev.status },
        { name: "requests", value: String(ev.requests) },
        ...tokens(ev.usage),
        ...failure(ev.error),
      ];
    case "context.opened":
      return [
        { value: `${ev.provider}/${ev.model_id}` },
        { name: "context_window", value: String(ev.context_window) },
      ];
    case "mcp_connect.started":
      return [{ value: ev.servers.join(", ") }];
    case "mcp_connect.done":
      return [
        { value: ev.status },
        ...ev.results.map((r) => ({ name: r.server, value: r.status })),
        ...failure(ev.error),
      ];
    case "tools.ready":
      return [
        { value: String(ev.tools.length) },
        { value: ev.tools.map((t) => t.name).join(", "), quiet: true },
      ];
    case "request.started":
      return [{ value: `#${ev.request}` }];
    case "request.done":
      return [
        { value: `#${ev.request}` },
        { value: ev.status },
        ...tokens(ev.usage),
        ...(ev.attempt !== undefined ? [{ name: "attempt", value: String(ev.attempt) }] : []),
        ...(ev.retry_in_ms !== undefined
          ? [{ name: "retry_in_ms", value: String(ev.retry_in_ms) }]
          : []),
        ...failure(ev.error),
      ];
    case "approval.requested":
      return [{ value: ev.tool_call.name }, { value: cut(ev.tool_call.arguments), quiet: true }];
    case "approval.decided":
      return [{ value: ev.decision }];
    case "compaction.started":
      return [
        { value: ev.reason },
        { name: "mode", value: ev.mode },
        { name: "context", value: String(ev.context) },
        { name: "turns", value: String(ev.turns) },
      ];
    case "compaction.done":
      return [
        { value: ev.reason },
        { name: "mode", value: ev.mode },
        { value: ev.status },
        ...tokens(ev.usage),
        ...failure(ev.error),
      ];
    case "hook.fired":
      return [
        { value: ev.hook },
        { value: ev.name },
        ...(ev.decision !== undefined ? [{ name: "decision", value: ev.decision }] : []),
        ...(ev.reason !== undefined ? [{ value: ev.reason, quiet: true }] : []),
      ];
    default: {
      // A type this panel does not know (the protocol adds them within /v1): what it carries.
      const rest = Object.fromEntries(
        Object.entries(ev).filter(([field]) => field !== "type" && field !== "at"),
      );
      return [{ value: cut(JSON.stringify(rest)), quiet: true }];
    }
  }
}

/** The rows with every open item that `close` picks marked complete. */
function closeOpen(rows: TryRow[], close: (row: TryItemRow) => boolean): TryRow[] {
  return rows.map((row) =>
    row.kind === "item" && row.open && close(row) ? { ...row, open: false } : row,
  );
}

/**
 * The rendered view's rows with one more payload: an item's event lands on that item's open row
 * (or opens one), anything else is a row of its own. Rows keep their places.
 */
export function addPayload(rows: readonly TryRow[], payload: string): TryRow[] {
  const id = rows.length;
  const ev = parseEvent(payload);
  if (ev === null) {
    return [
      ...rows,
      { kind: "event", id, type: "?", fields: [{ value: cut(payload), quiet: true }] },
    ];
  }
  const dot = ev.type.lastIndexOf(".");
  const item = ev.type.slice(0, dot);
  const phase = ev.type.slice(dot + 1);
  if (ITEMS.has(item) && (phase === "delta" || phase === "done")) {
    const key = itemKey(ev, item);
    const at = rows.findLastIndex((r) => r.kind === "item" && r.open && r.key === key);
    const prev = at >= 0 ? (rows[at] as TryItemRow) : undefined;
    const row = itemRow(prev, id, ev, item, phase === "done");
    return at >= 0 ? rows.map((r, i) => (i === at ? row : r)) : [...rows, row];
  }
  const origin = originOf(ev);
  let kept = [...rows];
  // A streamed summary has no `.done`: its compaction's end is what completes it.
  if (ev.type === "compaction.done") {
    kept = closeOpen(kept, (r) => r.item === "summary" && r.origin === origin);
  }
  // Nothing of a run is still coming after its end.
  if (ev.type === "run.done") kept = closeOpen(kept, () => true);
  return [
    ...kept,
    {
      kind: "event",
      id,
      type: ev.type,
      fields: eventFields(ev),
      ...(origin !== undefined ? { origin } : {}),
      ...(ev.type === "approval.requested"
        ? { approval: { toolCallId: ev.tool_call.tool_call_id, pending: true } }
        : {}),
    },
  ];
}

/** Milliseconds from `run.started` to `run.done`, by the server's clock; null when unreadable. */
export function elapsedMs(started: string, done: string): number | null {
  const ms = Date.parse(done) - Date.parse(started);
  return Number.isFinite(ms) && ms >= 0 ? ms : null;
}

/** The two views of a run: its rows with fragments merged, or its payloads as received. */
export type TryView = "rendered" | "raw";

export interface TryState {
  input: string;
  running: boolean;
  /** The Session the last run named: the next run continues it. */
  sessionId: string | null;
  /** The current run's `run.started` time; null until it arrives, so Stop knows whom to ask. */
  startedAt: string | null;
  /** The current run's payloads, exactly as received. */
  payloads: string[];
  /** The rendered view's rows. */
  rows: TryRow[];
  view: TryView;
  /** The run's outcome, once `run.done` arrived. */
  result: { run: RunResult; elapsedMs: number | null } | null;
  /** A refusal before the stream. */
  error: { status: number; code: string; message: string } | null;
  /** The body ended before `run.done`. */
  broken: boolean;
  /** `[DONE]` arrived. */
  closed: boolean;
}

export type TryAction =
  | { type: "input"; text: string }
  | { type: "start" }
  | { type: "payload"; data: string }
  | { type: "httpError"; status: number; code: string; message: string }
  /** The body closed; `stopped` when it was this panel that closed it (Stop before run.started, leaving). */
  | { type: "ended"; stopped?: boolean }
  | { type: "view"; view: TryView }
  | { type: "decided"; toolCallId: string }
  | { type: "reset" };

/** The panel before its first run: the example in the input, no Session. */
export function initialTryState(input: string): TryState {
  return {
    input,
    running: false,
    sessionId: null,
    startedAt: null,
    payloads: [],
    rows: [],
    view: "rendered",
    result: null,
    error: null,
    broken: false,
    closed: false,
  };
}

/** The rows with the approval of `toolCallId` (or, without one, every approval) no longer open. */
function settle(rows: TryRow[], toolCallId?: string): TryRow[] {
  return rows.map((r) =>
    r.kind === "event" &&
    r.approval?.pending === true &&
    (toolCallId === undefined || r.approval.toolCallId === toolCallId)
      ? { ...r, approval: { ...r.approval, pending: false } }
      : r,
  );
}

/** What the run comes to, folded from every payload it sent; null when the stream never said. */
function resultOf(payloads: readonly string[], doneAt: string, startedAt: string | null) {
  const collector = new RunCollector();
  for (const payload of payloads) {
    const ev = parseEvent(payload);
    if (ev !== null) collector.add(ev);
  }
  try {
    return {
      run: collector.result(),
      elapsedMs: startedAt === null ? null : elapsedMs(startedAt, doneAt),
    };
  } catch {
    return null;
  }
}

export function reduceTry(state: TryState, action: TryAction): TryState {
  switch (action.type) {
    case "input":
      return { ...state, input: action.text };
    case "start":
      return {
        ...state,
        running: true,
        startedAt: null,
        payloads: [],
        rows: [],
        result: null,
        error: null,
        broken: false,
        closed: false,
      };
    case "payload": {
      if (action.data === "[DONE]") return { ...state, closed: true };
      const payloads = [...state.payloads, action.data];
      const rows = addPayload(state.rows, action.data);
      const ev = parseEvent(action.data);
      if (ev?.type === "run.started") {
        return { ...state, payloads, rows, sessionId: ev.session_id, startedAt: ev.at };
      }
      if (ev?.type === "approval.decided") {
        return { ...state, payloads, rows: settle(rows, ev.tool_call_id) };
      }
      if (ev?.type === "run.done") {
        // Finished: the input clears for a follow-up on the same Session.
        return {
          ...state,
          payloads,
          rows: settle(rows),
          result: resultOf(payloads, ev.at, state.startedAt),
          input: "",
        };
      }
      return { ...state, payloads, rows };
    }
    case "httpError":
      return {
        ...state,
        running: false,
        error: { status: action.status, code: action.code, message: action.message },
      };
    case "ended":
      return {
        ...state,
        running: false,
        rows: settle(closeOpen(state.rows, () => true)),
        broken: action.stopped !== true && state.result === null && state.error === null,
      };
    case "view":
      return { ...state, view: action.view };
    case "decided":
      return { ...state, rows: settle(state.rows, action.toolCallId) };
    case "reset":
      return { ...initialTryState(state.input), view: state.view };
  }
}

/** The request the next run sends: the input, and the Session to continue once there is one. */
export function tryBody(state: TryState): RunRequest {
  return {
    input: state.input,
    ...(state.sessionId !== null ? { session_id: state.sessionId } : {}),
  };
}

/** The `data:` lines as received, `[DONE]` last once it came: what the raw view prints. */
export function rawLines(state: Pick<TryState, "payloads" | "closed">): string[] {
  const lines = state.payloads.map((payload) => `data: ${payload}`);
  return state.closed ? [...lines, "data: [DONE]"] : lines;
}

/** The Agent a run goes to. */
export interface TryTarget {
  projectId: string;
  agentId: string;
}

/**
 * One run: the request through the try route, then one `payload` per event of the body as it
 * arrives, then `ended`. A refusal before the stream is `httpError`; aborting `signal` (Stop
 * before run.started, or leaving the tab) ends it as stopped.
 */
export async function runTry(
  target: TryTarget,
  dispatch: (action: TryAction) => void,
  body: RunRequest,
  signal: AbortSignal,
): Promise<void> {
  dispatch({ type: "start" });
  try {
    const res = await api.tryAgentApi(target.projectId, target.agentId, body, { signal });
    if (res.body !== null) {
      for await (const data of readSse(res.body)) dispatch({ type: "payload", data });
    }
    dispatch({ type: "ended" });
  } catch (err) {
    if (signal.aborted) dispatch({ type: "ended", stopped: true });
    else if (err instanceof ApiError) {
      dispatch({ type: "httpError", status: err.status, code: err.code, message: err.message });
    } else dispatch({ type: "ended" });
  }
}

/**
 * Stop: once the run has named its Session, the Session's abort route — the stream stays open
 * and ends with `run.done` aborted, as a program sees it; before that, the request itself is
 * aborted.
 */
export async function stopTry(state: TryState, controller: AbortController | null): Promise<void> {
  if (state.startedAt !== null && state.sessionId !== null) {
    await api.postAbort(state.sessionId);
    return;
  }
  controller?.abort();
}

/**
 * An inline answer to an approval the run asked for, through the Session's approvals route; its
 * buttons go at once, and the stream's `approval.decided` says how it was decided.
 */
export async function answerApproval(
  sessionId: string,
  toolCallId: string,
  decision: "allow" | "deny",
  dispatch: (action: TryAction) => void,
): Promise<void> {
  await api.postApproval(sessionId, toolCallId, { decision });
  dispatch({ type: "decided", toolCallId });
}