cortena-ui 1.4.2 → 1.5.0

package/src/agent-chat/agui-client.ts

@@ -0,0 +1,405 @@
+/**
+ * `AgentChatClient` over AG-UI.
+ *
+ * Ported from `cortena-shared/src/agui/client.ts` (Cortena monorepo,
+ * DESIGN-37). `cortena-shared` is not published, so what this package needs is
+ * copied rather than imported; keep the two in step.
+ *
+ * **This is the only module in cortena-ui that imports `@ag-ui/client`**, and
+ * `cortena-ui/agent-chat` is the only entry that reaches it. `@ag-ui/client`
+ * brings rxjs, zod 3, uuid and protobuf; `test/bundle-probe.test.mjs` asserts
+ * none of it is reachable from `cortena-ui` or `cortena-ui/core`.
+ *
+ * It is an OPTIONAL peer, and the import is therefore **lazy**: a static
+ * `import { HttpAgent }` made the whole `cortena-ui/agent-chat` entry fail to
+ * load for a consumer that had not installed it, so an extension on another
+ * transport could not draw `AgentChatPopup` at all — a package it never asked
+ * for decided whether its chat rendered. Loading it inside the factory keeps
+ * the entry resolvable, and moves the failure to the one operation that
+ * genuinely needs the peer, with a message that says what to install.
+ *
+ * What an extension must expose for this to work is in README.md, "The agent
+ * pop-up": `POST /agui/run`, `/agui/abort`, `/agui/approval` and the two
+ * control-plane reads, all proxied through the extension's own gateway with the
+ * signed-in user's JWT — never a service token.
+ *
+ * Two things about the wire that are easy to get wrong:
+ *
+ * - The stream ends by **closing the connection** after `RUN_FINISHED` or
+ *   `RUN_ERROR`. There is no `data: [DONE]` sentinel; emitting one makes the
+ *   AG-UI client error the subject, because it `JSON.parse`s every `data:` line.
+ * - Approvals go to their own endpoint. Sending a decision as `state` on a
+ *   second `/agui/run` opens a second concurrent stream, and two mappers then
+ *   write two sets of message ids into one bridge, which resets its text buffer
+ *   whenever the message id changes.
+ */
+
+import type { HttpAgent } from "@ag-ui/client";
+import { AgentChatBridge } from "./bridge";
+import type {
+  AgentApprovalContext,
+  AgentApprovalDecision,
+  AgentApprovalEvent,
+  AgentChatClient,
+  AgentChatEvent,
+  AgentChatSendInput,
+  AgentToolEvent,
+} from "./types";
+
+export interface CreateAguiAgentChatClientOptions {
+  /**
+   * Origin the AG-UI and control-plane paths hang off, no trailing slash.
+   * For an extension this is its own gateway, which proxies to cortenacore.
+   */
+  baseUrl: string;
+  /** The signed-in USER's JWT. Read on every request, never captured once. */
+  getToken: () => string;
+  /** The agent template slug — the extension id. Sessions are `agent:<id>:…`. */
+  agentId: string;
+  fetchImpl?: typeof fetch;
+  /** Frontend tools advertised on every run; AG-UI requires a description. */
+  tools?: Array<{ name: string; description: string; parameters?: unknown }>;
+  /** Backoff before re-attaching a dropped stream. */
+  reconnectDelays?: readonly number[];
+  maxReconnectAttempts?: number;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+
+const DEFAULT_RECONNECT_DELAYS: readonly number[] = [500, 1_000, 2_000, 5_000, 10_000];
+const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
+
+const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * What a relative `baseUrl` resolves against.
+ *
+ * The browser's own origin, and a placeholder under Node — where this module
+ * is exercised by tests with a `fetchImpl` stub and there is no origin to
+ * speak of. The placeholder never reaches the network: the stub sees the
+ * resolved string, and `/api/core/...` is what it asserts on.
+ */
+function requestBase(): string {
+  return typeof location === "undefined" ? "http://cortena.invalid" : location.origin;
+}
+
+/** What `@ag-ui/client` exports and this module constructs. */
+type HttpAgentConstructor = typeof import("@ag-ui/client").HttpAgent;
+
+export const MISSING_AGUI_PEER =
+  'cortena-ui/agent-chat: the AG-UI transport needs the optional peer "@ag-ui/client". ' +
+  "Install it (pnpm add @ag-ui/client), or pass your own AgentChatClient to AgentChat.";
+
+/**
+ * `@ag-ui/client`, on demand.
+ *
+ * The specifier is a literal so a bundler still sees the dependency and puts
+ * it in a chunk of its own — `test/bundle-probe.test.mjs` measures that the
+ * agent-chat entry carries it. What changes is *when* it is evaluated, and
+ * what happens when it is not there at all.
+ */
+async function loadHttpAgent(): Promise<HttpAgentConstructor> {
+  try {
+    return (await import("@ag-ui/client")).HttpAgent;
+  } catch (cause) {
+    throw new Error(MISSING_AGUI_PEER, { cause });
+  }
+}
+
+type Sink<T> = (event: T) => void;
+
+interface ActiveRun {
+  runId: string;
+  sessionKey: string;
+  bridge: AgentChatBridge;
+  agent: HttpAgent;
+  aborted: boolean;
+}
+
+class AguiAgentChatClient implements AgentChatClient {
+  readonly agentId: string;
+
+  private readonly opts: CreateAguiAgentChatClientOptions;
+  private readonly delays: readonly number[];
+  private readonly maxAttempts: number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly chatSinks = new Set<Sink<AgentChatEvent>>();
+  private readonly toolSinks = new Set<Sink<AgentToolEvent>>();
+  private readonly approvalSinks = new Set<Sink<AgentApprovalEvent>>();
+  private active: ActiveRun | null = null;
+  /** The optional peer, requested when the client is created and awaited per run. */
+  private readonly httpAgent: Promise<HttpAgentConstructor>;
+
+  constructor(opts: CreateAguiAgentChatClientOptions) {
+    this.opts = opts;
+    this.agentId = opts.agentId;
+    this.delays = opts.reconnectDelays ?? DEFAULT_RECONNECT_DELAYS;
+    this.maxAttempts = opts.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    this.sleep = opts.sleep ?? defaultSleep;
+    // Started here so a missing peer is discovered when the client is made
+    // rather than mid-stream. The rejection is answered immediately: a client
+    // created and never sent to must not raise an unhandled rejection, and
+    // `startRun` awaits the same promise where the user can be told.
+    this.httpAgent = loadHttpAgent();
+    this.httpAgent.catch(() => {});
+  }
+
+  onChat(sink: Sink<AgentChatEvent>): () => void {
+    this.chatSinks.add(sink);
+    return () => this.chatSinks.delete(sink);
+  }
+
+  onTool(sink: Sink<AgentToolEvent>): () => void {
+    this.toolSinks.add(sink);
+    return () => this.toolSinks.delete(sink);
+  }
+
+  onApproval(sink: Sink<AgentApprovalEvent>): () => void {
+    this.approvalSinks.add(sink);
+    return () => this.approvalSinks.delete(sink);
+  }
+
+  get runUrl(): string {
+    return `${this.opts.baseUrl}/agui/run`;
+  }
+
+  get abortUrl(): string {
+    return `${this.opts.baseUrl}/agui/abort`;
+  }
+
+  get approvalUrl(): string {
+    return `${this.opts.baseUrl}/agui/approval`;
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      authorization: `Bearer ${this.opts.getToken()}`,
+      "content-type": "application/json",
+    };
+  }
+
+  private get fetch(): typeof fetch {
+    return this.opts.fetchImpl ?? globalThis.fetch;
+  }
+
+  /** `sessions.list` and `chat.history` over the REST control plane. */
+  async request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T> {
+    const path = `${this.opts.baseUrl}/api/core/${method.split(".").join("/")}`;
+    const readOnly = method === "sessions.list" || method === "chat.history";
+    // `new URL(path)` with no base throws on a relative `baseUrl`, and the one
+    // in this module's own example is `"/api/agent"` — the shape every
+    // extension uses, since the gateway that proxies these calls is the app's
+    // own origin. `sessions.list` therefore threw before it was ever sent, and
+    // the chat opened on "The agent could not be reached".
+    const url = new URL(path, requestBase());
+    if (readOnly) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const response = await this.fetch(url.toString(), {
+      method: readOnly ? "GET" : "POST",
+      headers: this.headers(),
+      ...(readOnly ? {} : { body: JSON.stringify(params) }),
+    });
+    if (!response.ok) {
+      throw new Error(await readError(response, method));
+    }
+    return (await response.json()) as T;
+  }
+
+  async send(input: AgentChatSendInput): Promise<void> {
+    // Fire and forget: the caller only awaits the acceptance. Events follow on
+    // the stream, exactly as they do when the server acknowledges a send.
+    void this.startRun(input);
+  }
+
+  private async startRun(input: AgentChatSendInput): Promise<void> {
+    const bridge = new AgentChatBridge({
+      runId: input.runId,
+      sessionKey: input.sessionKey,
+      chat: (event) => this.emit(this.chatSinks, event),
+      tool: (event) => this.emit(this.toolSinks, event),
+      approval: (event) => this.emit(this.approvalSinks, event),
+      ...(this.opts.now ? { now: this.opts.now } : {}),
+    });
+
+    const forwarded: Record<string, unknown> = {
+      ...(input.thinking ? { thinking: input.thinking } : {}),
+      ...(input.attachments?.length ? { attachments: input.attachments } : {}),
+      ...(input.model ? { model: input.model } : {}),
+      // A click inside a rendered A2UI surface or MCP App. Structured rather
+      // than typed prose: cortenacore turns it into the documented envelope.
+      ...(input.a2uiAction ? { a2uiAction: input.a2uiAction } : {}),
+      ...(input.mcpAppAction ? { mcpAppAction: input.mcpAppAction } : {}),
+    };
+
+    let Agent: HttpAgentConstructor;
+    try {
+      Agent = await this.httpAgent;
+    } catch (err) {
+      // The one operation that needs the peer, and the only place it can be
+      // reported: in the chat, as a failed run, rather than as a rejected
+      // promise nobody is holding.
+      bridge.fail(err instanceof Error ? err.message : MISSING_AGUI_PEER);
+      return;
+    }
+
+    let attempt = 0;
+    let resume = false;
+    for (;;) {
+      const runId = resume ? `${input.runId}:resume-${attempt}` : input.runId;
+      const agent = new Agent({
+        url: this.runUrl,
+        headers: this.headers(),
+        threadId: input.sessionKey,
+        // A re-attach carries no new user message; the server re-streams the
+        // run named by forwardedProps.resumeRunId instead of starting one.
+        initialMessages: resume
+          ? []
+          : [{ id: input.runId, role: "user", content: input.message }],
+        ...(this.opts.fetchImpl ? { fetch: this.opts.fetchImpl } : {}),
+      });
+      this.active = {
+        runId: input.runId,
+        sessionKey: input.sessionKey,
+        bridge,
+        agent,
+        aborted: this.active?.aborted === true && this.active.runId === input.runId,
+      };
+      try {
+        await agent.runAgent(
+          {
+            runId,
+            ...(this.opts.tools?.length ? { tools: this.opts.tools } : {}),
+            forwardedProps: {
+              ...forwarded,
+              ...(resume ? { resumeRunId: input.runId } : {}),
+            },
+          },
+          { onEvent: ({ event }) => bridge.handleEvent(event as never) },
+        );
+        return;
+      } catch (err) {
+        if (bridge.finished || this.active?.aborted) {
+          return;
+        }
+        attempt += 1;
+        if (attempt > this.maxAttempts) {
+          bridge.fail(err instanceof Error ? err.message : "The agent stream failed");
+          return;
+        }
+        await this.sleep(this.delays[Math.min(attempt - 1, this.delays.length - 1)] ?? 1_000);
+        // The backoff is up to ten seconds long, and everything can change in
+        // it: the user presses Stop, or a late RUN_FINISHED lands on the
+        // bridge. Checking only before the sleep re-attached to a run that had
+        // already ended — a second stream, a second set of message ids into
+        // one bridge, and an abort the user watched do nothing.
+        if (bridge.finished || this.active?.aborted) {
+          return;
+        }
+        resume = true;
+      }
+    }
+  }
+
+  async abort(params?: { runId?: string; sessionKey?: string }): Promise<void> {
+    const active = this.active;
+    if (active) {
+      active.aborted = true;
+      try {
+        active.agent.abortRun();
+      } catch {
+        // Already finished; the POST below is still worth making.
+      }
+    }
+    const runId = params?.runId ?? active?.runId;
+    const threadId = params?.sessionKey ?? active?.sessionKey;
+    if (!runId || !threadId) {
+      return;
+    }
+    try {
+      await this.fetch(this.abortUrl, {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify({ runId, threadId }),
+      });
+    } catch {
+      // Best-effort: dropping the stream aborts the run server-side anyway.
+    }
+  }
+
+  /**
+   * Answer one approval, on the thread and run it arrived on.
+   *
+   * `this.active` is deliberately not consulted. An approval pauses a run, and
+   * a user is free to open another session from the drawer or start another
+   * turn while it waits — at which point `active.sessionKey` is a different
+   * conversation and "allow" would be sent against it. The request carried its
+   * own `{ runId, sessionKey }`; those are what go on the wire.
+   */
+  async resolveApproval(
+    id: string,
+    decision: AgentApprovalDecision,
+    context: AgentApprovalContext,
+  ): Promise<void> {
+    const response = await this.fetch(this.approvalUrl, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({
+        id,
+        decision,
+        threadId: context.sessionKey,
+        runId: context.runId,
+      }),
+    });
+    // A rejected decision has to reach the user. Swallowing it left the card
+    // gone, the run paused server-side and nothing on screen saying so — the
+    // user believes they answered and the agent believes nobody did.
+    if (!response.ok) {
+      throw new Error(await readError(response, "approval"));
+    }
+  }
+
+  private emit<T>(sinks: Set<Sink<T>>, event: T): void {
+    for (const sink of [...sinks]) {
+      sink(event);
+    }
+  }
+}
+
+/**
+ * An `AgentChatClient` that streams over AG-UI and reads sessions and history
+ * over the REST control plane.
+ *
+ * ```tsx
+ * const client = React.useMemo(
+ *   () => createAguiAgentChatClient({ baseUrl: "/api/agent", getToken: () => jwt, agentId: "tasks" }),
+ *   [jwt],
+ * );
+ * ```
+ */
+export function createAguiAgentChatClient(
+  options: CreateAguiAgentChatClientOptions,
+): AgentChatClient {
+  return new AguiAgentChatClient(options);
+}
+
+async function readError(response: Response, method: string): Promise<string> {
+  try {
+    const body = (await response.json()) as { error?: { message?: string } };
+    if (body?.error?.message) {
+      return body.error.message;
+    }
+  } catch {
+    // Not JSON. The status is all there is.
+  }
+  if (response.status === 404) {
+    // The single most common misconfiguration: the control-plane endpoints are
+    // off, so every path under /api/core answers 404 before authentication.
+    return `${method} is unavailable (404). Check that the AG-UI and control-plane endpoints are enabled.`;
+  }
+  return `${method} failed (${response.status})`;
+}