@app-vitals/agent-admin 0.0.1 → 0.1.1

package/src/http-chat-client.ts

@@ -0,0 +1,533 @@
+/**
+ * admin/src/http-chat-client.ts
+ * Chat service client for the admin service.
+ *
+ * Mirrors the HttpChatServiceProvisioningClient pattern for consistency.
+ * All methods call the chat service's thread + message API using an admin token.
+ */
+
+// ─── Types (inline — no cross-package coupling) ───────────────────────────────
+
+export interface ChatThread {
+  id: string;
+  agentId: string;
+  title: string | null;
+  memberId: string | null;
+  /**
+   * Agent-to-agent ask threads (COS-31.1): `kind: "ask"`, the asking agent's
+   * id and the ask depth. Optional so threads from a chat service that
+   * predates these columns deserialize cleanly.
+   */
+  kind?: string | null;
+  askFromAgentId?: string | null;
+  askDepth?: number | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MessageTokens {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens?: number;
+  cache_creation_input_tokens?: number;
+}
+
+export interface ChatMessage {
+  id: string;
+  threadId: string;
+  role: string;
+  body: string;
+  createdAt: string;
+  claimedBy: string | null;
+  claimed?: boolean;
+  claimedAt?: string | null;
+  heartbeatAt?: string | null;
+  repliedAt: string | null;
+  tokens: MessageTokens | null;
+  costUsd: number | null;
+  errorKind?: string | null;
+  attachmentFilename: string | null;
+  attachmentSize: number | null;
+  /**
+   * Live-progress columns (added chat-side in CFB-2.2). The agent's heartbeat
+   * reports a coarse `progressPhase` (one of lib/progress-phases.ts's closed
+   * set, or null before the first phase is reported) and bumps `progressSeq`
+   * every time it makes forward progress. `cancelRequestedAt` is set when a
+   * cancel has been requested for the in-flight reply. All optional so older
+   * fixtures / responses that predate these columns deserialize cleanly.
+   */
+  progressPhase?: string | null;
+  progressSeq?: number;
+  cancelRequestedAt?: string | null;
+}
+
+export interface ThreadStats {
+  messageCount: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCostUsd: number;
+}
+
+/** Optional file attachment carried alongside a created message. */
+interface MessageAttachment {
+  filename: string;
+  size: number;
+  bytes: Uint8Array;
+}
+
+export interface ListThreadsResult {
+  threads: ChatThread[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+interface ListMessagesResult {
+  messages: ChatMessage[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+export interface ListThreadsOptions {
+  limit?: number;
+  offset?: number;
+}
+
+interface ListMessagesOptions {
+  limit?: number;
+  offset?: number;
+  /**
+   * Return only messages ordered *after* the message with this id. Applied as
+   * a read-side filter over the full ordered result (the chat service itself
+   * only understands limit/offset), so incremental polls stay cheap without
+   * changing the chat service HTTP API.
+   */
+  since?: string;
+}
+
+interface CreateThreadOptions {
+  title?: string;
+  memberId?: string;
+  /** Thread kind; "ask" marks an agent-to-agent ask thread (COS-31.1). */
+  kind?: "ask";
+  /** Id of the agent that asked (ask threads only). */
+  askFromAgentId?: string;
+  /** Ask chain depth (ask threads only; admin always sends 1). */
+  askDepth?: number;
+}
+
+interface UpdateThreadOptions {
+  title?: string;
+}
+
+// ─── Interface ────────────────────────────────────────────────────────────────
+
+export interface ChatClient {
+  listThreads(
+    agentId?: string,
+    opts?: ListThreadsOptions,
+  ): Promise<ListThreadsResult>;
+
+  getThread(id: string): Promise<ChatThread>;
+
+  createThread(
+    agentId: string,
+    opts?: CreateThreadOptions,
+  ): Promise<ChatThread>;
+
+  updateThread(id: string, data: UpdateThreadOptions): Promise<ChatThread>;
+
+  deleteThread(id: string): Promise<void>;
+
+  listMessages(
+    threadId: string,
+    opts?: ListMessagesOptions,
+  ): Promise<ListMessagesResult>;
+
+  createMessage(
+    threadId: string,
+    role: string,
+    body: string,
+    attachment?: MessageAttachment,
+  ): Promise<ChatMessage>;
+
+  getThreadStats(threadId: string): Promise<ThreadStats>;
+
+  /**
+   * Fetch a message's attachment bytes + filename, for proxying playback/
+   * download back to the browser (VM-3.1) — the browser never holds the
+   * chat service's admin bearer token, so it cannot call the chat service's
+   * GET /:id/attachment directly. Returns null when the message has no
+   * attachment (e.g. a user-authored attachment already cleared by the
+   * ephemeral-retention policy — see chat/src/routes/messages.ts).
+   */
+  getAttachment(
+    threadId: string,
+    messageId: string,
+  ): Promise<{ bytes: Uint8Array; filename: string } | null>;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Return only the messages ordered *after* the message whose id is `since`,
+ * assuming `messages` is in chronological order. If `since` isn't found (e.g.
+ * the client's last-seen id was trimmed away), returns the full list so the
+ * caller re-syncs rather than silently dropping everything.
+ */
+export function filterSince(
+  messages: ChatMessage[],
+  since: string,
+): ChatMessage[] {
+  const idx = messages.findIndex((m) => m.id === since);
+  return idx === -1 ? messages : messages.slice(idx + 1);
+}
+
+/**
+ * Project a chat-service message onto the explicit field set the admin's
+ * messages.json poll response carries, plus any extras the caller computes
+ * (e.g. the server-rendered `bubbleHtml`). Never spread the upstream object:
+ * the chat service once leaked its raw `attachmentBytes` column, and passing
+ * that through JSON-expanded a few MB of audio into ~36 MB per poll.
+ */
+export function toPolledMessage<Extra extends Record<string, unknown>>(
+  m: ChatMessage,
+  extra: Extra,
+): ChatMessage & Extra {
+  return {
+    id: m.id,
+    threadId: m.threadId,
+    role: m.role,
+    body: m.body,
+    createdAt: m.createdAt,
+    claimedBy: m.claimedBy,
+    claimed: m.claimed,
+    claimedAt: m.claimedAt,
+    heartbeatAt: m.heartbeatAt,
+    repliedAt: m.repliedAt,
+    tokens: m.tokens,
+    costUsd: m.costUsd,
+    errorKind: m.errorKind,
+    attachmentFilename: m.attachmentFilename,
+    attachmentSize: m.attachmentSize,
+    progressPhase: m.progressPhase,
+    progressSeq: m.progressSeq,
+    cancelRequestedAt: m.cancelRequestedAt,
+    ...extra,
+  };
+}
+
+// ─── Http implementation ──────────────────────────────────────────────────────
+
+export class HttpChatClient implements ChatClient {
+  private readonly fetchFn: typeof fetch;
+
+  constructor(
+    private readonly baseUrl: string,
+    private readonly adminToken: string,
+    opts?: { fetchFn?: typeof fetch },
+  ) {
+    this.fetchFn = opts?.fetchFn ?? fetch;
+  }
+
+  private authHeaders(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.adminToken}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  async listThreads(
+    agentId?: string,
+    opts?: ListThreadsOptions,
+  ): Promise<ListThreadsResult> {
+    const params = new URLSearchParams();
+    if (agentId) params.set("agentId", agentId);
+    if (opts?.limit !== undefined) params.set("limit", String(opts.limit));
+    if (opts?.offset !== undefined) params.set("offset", String(opts.offset));
+    const qs = params.size > 0 ? `?${params}` : "";
+    const res = await this.fetchFn(`${this.baseUrl}/threads${qs}`, {
+      headers: this.authHeaders(),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `chat-service GET /threads failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    return res.json() as Promise<ListThreadsResult>;
+  }
+
+  async getThread(id: string): Promise<ChatThread> {
+    const res = await this.fetchFn(`${this.baseUrl}/threads/${id}`, {
+      headers: this.authHeaders(),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `chat-service GET /threads/${id} failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    return res.json() as Promise<ChatThread>;
+  }
+
+  async createThread(
+    agentId: string,
+    opts?: CreateThreadOptions,
+  ): Promise<ChatThread> {
+    const res = await this.fetchFn(`${this.baseUrl}/threads`, {
+      method: "POST",
+      headers: this.authHeaders(),
+      body: JSON.stringify({
+        agentId,
+        ...(opts?.title ? { title: opts.title } : {}),
+        ...(opts?.memberId ? { memberId: opts.memberId } : {}),
+        ...(opts?.kind ? { kind: opts.kind } : {}),
+        ...(opts?.askFromAgentId
+          ? { askFromAgentId: opts.askFromAgentId }
+          : {}),
+        ...(opts?.askDepth !== undefined ? { askDepth: opts.askDepth } : {}),
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `chat-service POST /threads failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    return res.json() as Promise<ChatThread>;
+  }
+
+  async updateThread(
+    id: string,
+    data: UpdateThreadOptions,
+  ): Promise<ChatThread> {
+    const res = await this.fetchFn(`${this.baseUrl}/threads/${id}`, {
+      method: "PATCH",
+      headers: this.authHeaders(),
+      body: JSON.stringify(data),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `chat-service PATCH /threads/${id} failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    return res.json() as Promise<ChatThread>;
+  }
+
+  async deleteThread(id: string): Promise<void> {
+    const res = await this.fetchFn(`${this.baseUrl}/threads/${id}`, {
+      method: "DELETE",
+      headers: this.authHeaders(),
+    });
+    if (!res.ok) {
+      throw new Error(
+        `chat-service DELETE /threads/${id} failed: ${res.status} ${res.statusText}`,
+      );
+    }
+  }
+
+  async listMessages(
+    threadId: string,
+    opts?: ListMessagesOptions,
+  ): Promise<ListMessagesResult> {
+    const params = new URLSearchParams();
+    if (opts?.limit !== undefined) params.set("limit", String(opts.limit));
+    if (opts?.offset !== undefined) params.set("offset", String(opts.offset));
+    const qs = params.size > 0 ? `?${params}` : "";
+    const res = await this.fetchFn(
+      `${this.baseUrl}/threads/${threadId}/messages${qs}`,
+      {
+        headers: this.authHeaders(),
+      },
+    );
+    if (!res.ok) {
+      throw new Error(
+        `chat-service GET /threads/${threadId}/messages failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    const result = (await res.json()) as ListMessagesResult;
+    if (opts?.since) {
+      return { ...result, messages: filterSince(result.messages, opts.since) };
+    }
+    return result;
+  }
+
+  async createMessage(
+    threadId: string,
+    role: string,
+    body: string,
+    attachment?: MessageAttachment,
+  ): Promise<ChatMessage> {
+    const payload: Record<string, unknown> = { role, body };
+    if (attachment) {
+      payload.attachmentBytes = Buffer.from(attachment.bytes).toString(
+        "base64",
+      );
+      payload.attachmentFilename = attachment.filename;
+      payload.attachmentSize = attachment.size;
+    }
+    const res = await this.fetchFn(
+      `${this.baseUrl}/threads/${threadId}/messages`,
+      {
+        method: "POST",
+        headers: this.authHeaders(),
+        body: JSON.stringify(payload),
+      },
+    );
+    if (!res.ok) {
+      throw new Error(
+        `chat-service POST /threads/${threadId}/messages failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    return res.json() as Promise<ChatMessage>;
+  }
+
+  async getThreadStats(threadId: string): Promise<ThreadStats> {
+    const res = await this.fetchFn(
+      `${this.baseUrl}/threads/${threadId}/stats`,
+      {
+        headers: this.authHeaders(),
+      },
+    );
+    if (!res.ok) {
+      throw new Error(
+        `chat-service GET /threads/${threadId}/stats failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    return res.json() as Promise<ThreadStats>;
+  }
+
+  async getAttachment(
+    threadId: string,
+    messageId: string,
+  ): Promise<{ bytes: Uint8Array; filename: string } | null> {
+    const res = await this.fetchFn(
+      `${this.baseUrl}/threads/${threadId}/messages/${messageId}/attachment`,
+      { headers: { Authorization: `Bearer ${this.adminToken}` } },
+    );
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new Error(
+        `chat-service GET /threads/${threadId}/messages/${messageId}/attachment failed: ${res.status} ${res.statusText}`,
+      );
+    }
+    const filename = parseAttachmentFilename(
+      res.headers.get("content-disposition"),
+    );
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    return { bytes, filename };
+  }
+}
+
+/**
+ * Extract the filename from a `Content-Disposition: attachment;
+ * filename="x"` header (as sent by chat/src/routes/messages.ts's
+ * getAttachmentRoute). Falls back to a generic name if the header is
+ * missing or unparsable.
+ */
+function parseAttachmentFilename(header: string | null): string {
+  if (!header) return "attachment";
+  const match = header.match(/filename="?([^";]+)"?/);
+  return match?.[1] ?? "attachment";
+}
+
+// ─── Noop implementation ──────────────────────────────────────────────────────
+
+export class NoopChatClient implements ChatClient {
+  async listThreads(
+    _agentId?: string,
+    _opts?: ListThreadsOptions,
+  ): Promise<ListThreadsResult> {
+    return { threads: [], total: 0, limit: 50, offset: 0 };
+  }
+
+  async getThread(_id: string): Promise<ChatThread> {
+    return {
+      id: "",
+      agentId: "",
+      title: null,
+      memberId: null,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  async createThread(
+    _agentId: string,
+    _opts?: CreateThreadOptions,
+  ): Promise<ChatThread> {
+    return {
+      id: "",
+      agentId: _agentId,
+      title: null,
+      memberId: null,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  async updateThread(
+    _id: string,
+    data: UpdateThreadOptions,
+  ): Promise<ChatThread> {
+    return {
+      id: _id,
+      agentId: "",
+      title: data.title ?? null,
+      memberId: null,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  async deleteThread(_id: string): Promise<void> {
+    // noop
+  }
+
+  async listMessages(
+    _threadId: string,
+    _opts?: ListMessagesOptions,
+  ): Promise<ListMessagesResult> {
+    return { messages: [], total: 0, limit: 50, offset: 0 };
+  }
+
+  async createMessage(
+    threadId: string,
+    role: string,
+    body: string,
+    attachment?: MessageAttachment,
+  ): Promise<ChatMessage> {
+    return {
+      id: "",
+      threadId,
+      role,
+      body,
+      createdAt: new Date().toISOString(),
+      claimedBy: null,
+      repliedAt: null,
+      tokens: null,
+      costUsd: null,
+      errorKind: null,
+      attachmentFilename: attachment?.filename ?? null,
+      attachmentSize: attachment?.size ?? null,
+      progressPhase: null,
+      progressSeq: 0,
+      cancelRequestedAt: null,
+    };
+  }
+
+  async getThreadStats(_threadId: string): Promise<ThreadStats> {
+    return {
+      messageCount: 0,
+      totalInputTokens: 0,
+      totalOutputTokens: 0,
+      totalCostUsd: 0,
+    };
+  }
+
+  async getAttachment(
+    _threadId: string,
+    _messageId: string,
+  ): Promise<{ bytes: Uint8Array; filename: string } | null> {
+    return null;
+  }
+}

package/src/http-chat-client.unit.test.ts

@@ -0,0 +1,119 @@
+/**
+ * admin/src/http-chat-client.unit.test.ts
+ * Pure unit tests for the read-side helpers in http-chat-client.ts.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import {
+  type ChatMessage,
+  filterSince,
+  HttpChatClient,
+} from "./http-chat-client.ts";
+
+const cassette: Record<string, { status: number; body: unknown }> = JSON.parse(
+  readFileSync(
+    new URL("./fixtures/http-chat-client-cassette.json", import.meta.url)
+      .pathname,
+    "utf-8",
+  ),
+);
+
+/** HttpChatClient over an injected fetchFn replaying one cassette entry. */
+function cassetteClient(key: string) {
+  const entry = cassette[key];
+  if (!entry) throw new Error(`cassette key not found: ${key}`);
+  const bodies: unknown[] = [];
+  const fetchFn = (async (_input: RequestInfo | URL, init?: RequestInit) => {
+    bodies.push(JSON.parse(String(init?.body ?? "{}")));
+    return new Response(JSON.stringify(entry.body), {
+      status: entry.status,
+      headers: { "Content-Type": "application/json" },
+    });
+  }) as typeof fetch;
+  return {
+    client: new HttpChatClient("https://chat.example.com", "admin-token", {
+      fetchFn,
+    }),
+    bodies,
+  };
+}
+
+function msg(id: string): ChatMessage {
+  return {
+    id,
+    threadId: "t",
+    role: "user",
+    body: id,
+    createdAt: "2024-01-01T00:00:00.000Z",
+    claimedBy: null,
+    repliedAt: null,
+    tokens: null,
+    costUsd: null,
+    errorKind: null,
+    attachmentFilename: null,
+    attachmentSize: null,
+  };
+}
+
+describe("filterSince (CFB-2.3 incremental ?since polling)", () => {
+  const messages = [msg("a"), msg("b"), msg("c"), msg("d")];
+
+  test("returns only messages after the given id", () => {
+    expect(filterSince(messages, "b").map((m) => m.id)).toEqual(["c", "d"]);
+  });
+
+  test("returns empty when since is the last message", () => {
+    expect(filterSince(messages, "d")).toEqual([]);
+  });
+
+  test("returns the full list when the since id is not found (re-sync)", () => {
+    expect(filterSince(messages, "zzz").map((m) => m.id)).toEqual([
+      "a",
+      "b",
+      "c",
+      "d",
+    ]);
+  });
+
+  test("returns everything after the first when since is the first id", () => {
+    expect(filterSince(messages, "a").map((m) => m.id)).toEqual([
+      "b",
+      "c",
+      "d",
+    ]);
+  });
+});
+
+describe("HttpChatClient.createThread ask fields (COS-31.1)", () => {
+  test("sends kind, askFromAgentId and askDepth when given", async () => {
+    const { client, bodies } = cassetteClient("createThread_ask_success");
+    const thread = await client.createThread("agent-123", {
+      title: "ask from agent-456 - 2026-01-03T00:00:00.000Z",
+      kind: "ask",
+      askFromAgentId: "agent-456",
+      askDepth: 1,
+    });
+    expect(bodies).toEqual([
+      {
+        agentId: "agent-123",
+        title: "ask from agent-456 - 2026-01-03T00:00:00.000Z",
+        kind: "ask",
+        askFromAgentId: "agent-456",
+        askDepth: 1,
+      },
+    ]);
+    expect(thread).toMatchObject({
+      id: "thread_ask",
+      kind: "ask",
+      askFromAgentId: "agent-456",
+      askDepth: 1,
+    });
+  });
+
+  test("omits the ask fields when not given", async () => {
+    const { client, bodies } = cassetteClient("createThread_minimal_success");
+    await client.createThread("agent-123", { title: "t" });
+    expect(bodies).toEqual([{ agentId: "agent-123", title: "t" }]);
+  });
+});