@app-vitals/agent-runtime 0.0.0-stage → 0.1.0

package/http-chat-service-client.integration.test.ts

@@ -0,0 +1,345 @@
+/**
+ * agent/src/runtime/http-chat-service-client.integration.test.ts
+ *
+ * Integration tests for HttpChatServiceClient against recorded chat-service
+ * REST API fixtures.
+ *
+ * Drives the client through an INJECTED fetchFn that replays canned Responses
+ * from cassette JSON files committed under ./fixtures/chat-service/ — no live
+ * API server, no global.fetch override, no mock.module(). Mirrors the pattern
+ * in admin/src/chat-service-provisioning-client.integration.test.ts.
+ *
+ * Companion to http-chat-service-client.unit.test.ts, which covers pure
+ * request-shaping logic via an inline injected double — this file instead
+ * reads response bodies from committed fixture JSON to exercise the
+ * "recorded dependency behavior" boundary per docs/testing.md.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  ChatServiceClientError,
+  HttpChatServiceClient,
+} from "./http-chat-service-client.ts";
+
+// ─── Cassettes ─────────────────────────────────────────────────────────────────
+
+interface CassetteEntry {
+  status: number;
+  /** When set to "base64", `body` is a base64 string decoded to raw bytes. */
+  bodyEncoding?: "base64";
+  body: unknown;
+}
+
+function loadCassette(filename: string): Record<string, CassetteEntry> {
+  // Beside the runtime source when extracted, one level up in the monorepo.
+  const path = [
+    join(import.meta.dir, "fixtures"),
+    join(import.meta.dir, "..", "fixtures"),
+  ]
+    .map((dir) => join(dir, "chat-service", filename))
+    .find((candidate) => existsSync(candidate)) as string;
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+const threadsCassette = loadCassette("threads.json");
+const messagesCassette = loadCassette("messages.json");
+const attachmentCassette = loadCassette("attachment.json");
+
+interface RecordedRequest {
+  url: string;
+  method: string;
+  headers: Headers;
+  body?: string;
+}
+
+/**
+ * Build a Response for a cassette entry. JSON entries get a JSON content
+ * type; base64-encoded entries (binary attachments) are decoded to raw bytes
+ * and returned without a JSON content type, matching what the real
+ * chat-service attachment endpoint sends.
+ */
+function responseForEntry(entry: CassetteEntry): Response {
+  if (entry.bodyEncoding === "base64") {
+    const bytes = Uint8Array.from(atob(entry.body as string), (c) =>
+      c.charCodeAt(0),
+    );
+    return new Response(bytes, {
+      status: entry.status,
+      statusText: `status-${entry.status}`,
+    });
+  }
+  return new Response(JSON.stringify(entry.body), {
+    status: entry.status,
+    statusText: `status-${entry.status}`,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+/**
+ * Build an injected fetchFn that replays the cassette entry for `key` from
+ * `cassette` on every call. Records the last request so tests can assert
+ * URL/method/headers.
+ */
+function cassetteFetch(
+  cassette: Record<string, CassetteEntry>,
+  key: string,
+): {
+  fetchFn: typeof fetch;
+  lastRequest: () => RecordedRequest;
+} {
+  let last: RecordedRequest | undefined;
+  const entry = cassette[key];
+  if (!entry) throw new Error(`cassette key not found: ${key}`);
+
+  const fetchFn = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+    last = {
+      url,
+      method: init?.method ?? "GET",
+      headers: new Headers(init?.headers),
+      body: typeof init?.body === "string" ? init.body : undefined,
+    };
+    return responseForEntry(entry);
+  }) as typeof fetch;
+
+  return {
+    fetchFn,
+    lastRequest: () => {
+      if (!last) throw new Error("fetchFn was not called");
+      return last;
+    },
+  };
+}
+
+const BASE_URL = "https://chat.example.com";
+const TOKEN = "chat-service-token-xyz";
+const THREAD_ID = "thread-abc";
+const MESSAGE_ID = "msg-xyz";
+
+function makeClient(
+  cassette: Record<string, CassetteEntry>,
+  key: string,
+): {
+  client: HttpChatServiceClient;
+  lastRequest: () => RecordedRequest;
+} {
+  const { fetchFn, lastRequest } = cassetteFetch(cassette, key);
+  const client = new HttpChatServiceClient({
+    baseUrl: BASE_URL,
+    token: TOKEN,
+    fetchFn,
+  });
+  return { client, lastRequest };
+}
+
+// ─── listThreads ───────────────────────────────────────────────────────────────
+
+describe("HttpChatServiceClient.listThreads (recorded fixtures)", () => {
+  it("returns the threads array from the recorded fixture on 200", async () => {
+    const { client, lastRequest } = makeClient(
+      threadsCassette,
+      "listThreads_success",
+    );
+
+    const result = await client.listThreads({});
+
+    const req = lastRequest();
+    expect(req.method).toBe("GET");
+    expect(req.headers.get("authorization")).toBe(`Bearer ${TOKEN}`);
+    expect(result.threads).toHaveLength(2);
+    expect(result.threads[0].id).toBe("thread-abc");
+    expect(result.threads[1].memberId).toBeNull();
+    expect(result.total).toBe(2);
+  });
+
+  it("sends agentId/limit/offset as query params and returns the paginated fixture", async () => {
+    const { client, lastRequest } = makeClient(
+      threadsCassette,
+      "listThreads_with_query_params",
+    );
+
+    const result = await client.listThreads({
+      agentId: "agent-1",
+      limit: 10,
+      offset: 5,
+    });
+
+    const req = lastRequest();
+    const url = new URL(req.url);
+    expect(url.pathname).toBe("/threads");
+    expect(url.searchParams.get("agentId")).toBe("agent-1");
+    expect(url.searchParams.get("limit")).toBe("10");
+    expect(url.searchParams.get("offset")).toBe("5");
+    expect(result.total).toBe(6);
+    expect(result.limit).toBe(10);
+    expect(result.offset).toBe(5);
+    expect(result.threads).toHaveLength(1);
+  });
+
+  it("throws ChatServiceClientError with statusCode 500 on the recorded server error", async () => {
+    const { client } = makeClient(threadsCassette, "listThreads_500");
+
+    const err = await client.listThreads({}).catch((e) => e);
+    expect(err).toBeInstanceOf(ChatServiceClientError);
+    expect(err.statusCode).toBe(500);
+  });
+});
+
+// ─── claimMessage ──────────────────────────────────────────────────────────────
+
+describe("HttpChatServiceClient.claimMessage (recorded fixtures)", () => {
+  it("returns the claimed message from the recorded fixture on 200", async () => {
+    const { client, lastRequest } = makeClient(
+      messagesCassette,
+      "claimMessage_success",
+    );
+
+    const result = await client.claimMessage(THREAD_ID);
+
+    const req = lastRequest();
+    expect(req.method).toBe("POST");
+    const url = new URL(req.url);
+    expect(url.pathname).toBe(`/threads/${THREAD_ID}/messages/claim`);
+    expect(req.headers.get("authorization")).toBe(`Bearer ${TOKEN}`);
+    expect(result).not.toBeNull();
+    expect(result?.id).toBe(MESSAGE_ID);
+    expect(result?.claimedBy).toBe("agent-1");
+  });
+
+  it("returns null on the recorded 404 (no unclaimed messages)", async () => {
+    const { client } = makeClient(messagesCassette, "claimMessage_404");
+
+    const result = await client.claimMessage(THREAD_ID);
+    expect(result).toBeNull();
+  });
+
+  it("throws ChatServiceClientError with statusCode 500 on the recorded server error", async () => {
+    const { client } = makeClient(messagesCassette, "claimMessage_500");
+
+    const err = await client.claimMessage(THREAD_ID).catch((e) => e);
+    expect(err).toBeInstanceOf(ChatServiceClientError);
+    expect(err.statusCode).toBe(500);
+  });
+});
+
+// ─── heartbeat ──────────────────────────────────────────────────────────────────
+
+describe("HttpChatServiceClient.heartbeat (recorded fixtures)", () => {
+  it("resolves and hits the recorded fixture on 200", async () => {
+    const { client, lastRequest } = makeClient(
+      messagesCassette,
+      "heartbeat_success",
+    );
+
+    const result = await client.heartbeat(THREAD_ID, MESSAGE_ID);
+    expect(result.cancelRequested).toBe(false);
+
+    const req = lastRequest();
+    expect(req.method).toBe("POST");
+    const url = new URL(req.url);
+    expect(url.pathname).toBe(
+      `/threads/${THREAD_ID}/messages/${MESSAGE_ID}/heartbeat`,
+    );
+    expect(req.headers.get("authorization")).toBe(`Bearer ${TOKEN}`);
+  });
+
+  it("throws ChatServiceClientError with statusCode 404 on the recorded not-found error", async () => {
+    const { client } = makeClient(messagesCassette, "heartbeat_404");
+
+    const err = await client.heartbeat(THREAD_ID, MESSAGE_ID).catch((e) => e);
+    expect(err).toBeInstanceOf(ChatServiceClientError);
+    expect(err.statusCode).toBe(404);
+  });
+});
+
+// ─── replyToMessage ────────────────────────────────────────────────────────────
+
+describe("HttpChatServiceClient.replyToMessage (recorded fixtures)", () => {
+  it("returns the reply result from the recorded fixture on 201", async () => {
+    const { client, lastRequest } = makeClient(
+      messagesCassette,
+      "replyToMessage_success",
+    );
+
+    const result = await client.replyToMessage(THREAD_ID, MESSAGE_ID, {
+      body: "Sure, here's how...",
+      tokens: { input_tokens: 120, output_tokens: 42 },
+      costUsd: 0.0021,
+    });
+
+    const req = lastRequest();
+    expect(req.method).toBe("POST");
+    const url = new URL(req.url);
+    expect(url.pathname).toBe(
+      `/threads/${THREAD_ID}/messages/${MESSAGE_ID}/reply`,
+    );
+    expect(req.headers.get("authorization")).toBe(`Bearer ${TOKEN}`);
+    expect(JSON.parse(req.body ?? "{}")).toEqual({
+      body: "Sure, here's how...",
+      tokens: { input_tokens: 120, output_tokens: 42 },
+      costUsd: 0.0021,
+    });
+    expect(result.userMessage.id).toBe(MESSAGE_ID);
+    expect(result.assistantMessage.role).toBe("assistant");
+    expect(result.assistantMessage.body).toBe("Sure, here's how...");
+    expect(result.assistantMessage.costUsd).toBe(0.0021);
+  });
+
+  it("throws ChatServiceClientError with statusCode 400 on the recorded bad-request error", async () => {
+    const { client } = makeClient(messagesCassette, "replyToMessage_400");
+
+    const err = await client
+      .replyToMessage(THREAD_ID, MESSAGE_ID, { body: "" })
+      .catch((e) => e);
+    expect(err).toBeInstanceOf(ChatServiceClientError);
+    expect(err.statusCode).toBe(400);
+  });
+});
+
+// ─── getAttachment ─────────────────────────────────────────────────────────────
+
+describe("HttpChatServiceClient.getAttachment (recorded fixtures)", () => {
+  it("returns the recorded binary bytes as a Uint8Array on 200", async () => {
+    const entry = attachmentCassette.getAttachment_success;
+    const expectedBytes = Uint8Array.from(atob(entry.body as string), (c) =>
+      c.charCodeAt(0),
+    );
+
+    const { client, lastRequest } = makeClient(
+      attachmentCassette,
+      "getAttachment_success",
+    );
+
+    const result = await client.getAttachment(THREAD_ID, MESSAGE_ID);
+
+    const req = lastRequest();
+    expect(req.method).toBe("GET");
+    const url = new URL(req.url);
+    expect(url.pathname).toBe(
+      `/threads/${THREAD_ID}/messages/${MESSAGE_ID}/attachment`,
+    );
+    expect(req.headers.get("authorization")).toBe(`Bearer ${TOKEN}`);
+    expect(result).not.toBeNull();
+    expect(result).toBeInstanceOf(Uint8Array);
+    expect(result).toEqual(expectedBytes);
+  });
+
+  it("returns null on the recorded 404 (no attachment)", async () => {
+    const { client } = makeClient(attachmentCassette, "getAttachment_404");
+
+    const result = await client.getAttachment(THREAD_ID, MESSAGE_ID);
+    expect(result).toBeNull();
+  });
+
+  it("throws ChatServiceClientError with statusCode 500 on the recorded server error", async () => {
+    const { client } = makeClient(attachmentCassette, "getAttachment_500");
+
+    const err = await client
+      .getAttachment(THREAD_ID, MESSAGE_ID)
+      .catch((e) => e);
+    expect(err).toBeInstanceOf(ChatServiceClientError);
+    expect(err.statusCode).toBe(500);
+  });
+});

package/http-chat-service-client.ts

@@ -0,0 +1,287 @@
+/**
+ * agent/src/runtime/http-chat-service-client.ts
+ *
+ * Typed HTTP client for the Shipwright chat service REST API.
+ *
+ * - ChatServiceClientError — typed error with statusCode
+ * - ChatServiceClient — interface for DI / testability
+ * - HttpChatServiceClient — production implementation with injectable fetchFn
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface Thread {
+  id: string;
+  agentId: string;
+  memberId: string | null;
+  title: string | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+}
+
+export interface Message {
+  id: string;
+  threadId: string;
+  role: string;
+  body: string;
+  claimedBy: string | null;
+  claimedAt: Date | string | null;
+  heartbeatAt: Date | string | null;
+  cancelRequestedAt: Date | string | null;
+  repliedAt: Date | string | null;
+  tokens: unknown;
+  costUsd: number | null;
+  attachmentFilename: string | null;
+  createdAt: Date | string;
+  updatedAt: Date | string;
+}
+
+/**
+ * Result of a heartbeat tick. The tick is bidirectional: the same request that
+ * proves liveness returns whether a cancel was requested, so there is no second
+ * polling loop and no inbound HTTP surface on the agent.
+ */
+interface HeartbeatResult {
+  /** True when cancelRequestedAt is set on the message — the run should abort. */
+  cancelRequested: boolean;
+}
+
+interface ReplyResult {
+  userMessage: Message;
+  assistantMessage: Message;
+}
+
+export interface ListThreadsOptions {
+  agentId?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ListThreadsResult {
+  threads: Thread[];
+  total: number;
+  limit: number;
+  offset: number;
+}
+
+interface ReplyOptions {
+  body: string;
+  tokens?: unknown;
+  costUsd?: number;
+  /** Stamped on the assistant message so the UI can offer a Retry action. */
+  errorKind?: string;
+  /** Filename for an optional reply attachment (e.g. synthesized speech audio). */
+  attachmentFilename?: string;
+  /** Byte size of `attachmentBytes`. Required alongside attachmentBytes. */
+  attachmentSize?: number;
+  /**
+   * Raw attachment bytes. Base64-encoded by replyToMessage() before being
+   * sent in the JSON body — callers pass raw bytes, not a pre-encoded string.
+   */
+  attachmentBytes?: Uint8Array;
+}
+
+// ─── Error ────────────────────────────────────────────────────────────────────
+
+export class ChatServiceClientError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ChatServiceClientError";
+  }
+}
+
+// ─── Interface ────────────────────────────────────────────────────────────────
+
+export interface ChatServiceClient {
+  listThreads(opts: ListThreadsOptions): Promise<ListThreadsResult>;
+  /** Returns null when there are no unclaimed messages in the thread. */
+  claimMessage(threadId: string): Promise<Message | null>;
+  /**
+   * Bump a claimed message's heartbeatAt — proof of life while a long-running
+   * reply is in progress — and learn whether a cancel was requested. The tick
+   * is bidirectional (see HeartbeatResult): the returned message carries
+   * cancelRequestedAt, from which cancelRequested is derived. Best-effort:
+   * callers should swallow failures rather than let a heartbeat blip abort the
+   * reply itself.
+   */
+  heartbeat(threadId: string, messageId: string): Promise<HeartbeatResult>;
+  replyToMessage(
+    threadId: string,
+    messageId: string,
+    opts: ReplyOptions,
+  ): Promise<ReplyResult>;
+  /**
+   * Fetch a message's attachment bytes. Returns null when there is no
+   * attachment (404). The chat service drops the bytes after serving them.
+   */
+  getAttachment(
+    threadId: string,
+    messageId: string,
+  ): Promise<Uint8Array | null>;
+}
+
+// ─── HttpChatServiceClient ────────────────────────────────────────────────────
+
+type FetchFn = (
+  url: RequestInfo | URL,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export class HttpChatServiceClient implements ChatServiceClient {
+  private readonly baseUrl: string;
+  private readonly token: string;
+  private readonly fetchFn: FetchFn;
+
+  constructor(opts: {
+    baseUrl: string;
+    token: string;
+    /** Injectable fetch for testing. Defaults to global fetch. */
+    fetchFn?: FetchFn;
+  }) {
+    // Strip trailing slash for clean URL construction
+    this.baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this.token = opts.token;
+    this.fetchFn = opts.fetchFn ?? fetch;
+  }
+
+  private authHeaders(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.token}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  async listThreads(opts: ListThreadsOptions): Promise<ListThreadsResult> {
+    const url = new URL(`${this.baseUrl}/threads`);
+    if (opts.agentId !== undefined)
+      url.searchParams.set("agentId", opts.agentId);
+    if (opts.limit !== undefined)
+      url.searchParams.set("limit", String(opts.limit));
+    if (opts.offset !== undefined)
+      url.searchParams.set("offset", String(opts.offset));
+
+    const res = await this.fetchFn(url.toString(), {
+      method: "GET",
+      headers: this.authHeaders(),
+    });
+
+    if (!res.ok) {
+      throw new ChatServiceClientError(
+        res.status,
+        `GET /threads failed: ${res.status}`,
+      );
+    }
+
+    return res.json() as Promise<ListThreadsResult>;
+  }
+
+  async claimMessage(threadId: string): Promise<Message | null> {
+    const url = `${this.baseUrl}/threads/${threadId}/messages/claim`;
+
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: this.authHeaders(),
+    });
+
+    // 404 = no unclaimed messages — not an error, just means nothing to do
+    if (res.status === 404) {
+      return null;
+    }
+
+    if (!res.ok) {
+      throw new ChatServiceClientError(
+        res.status,
+        `POST /threads/${threadId}/messages/claim failed: ${res.status}`,
+      );
+    }
+
+    return res.json() as Promise<Message>;
+  }
+
+  async heartbeat(
+    threadId: string,
+    messageId: string,
+  ): Promise<HeartbeatResult> {
+    const url = `${this.baseUrl}/threads/${threadId}/messages/${messageId}/heartbeat`;
+
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: this.authHeaders(),
+    });
+
+    if (!res.ok) {
+      throw new ChatServiceClientError(
+        res.status,
+        `POST /threads/${threadId}/messages/${messageId}/heartbeat failed: ${res.status}`,
+      );
+    }
+
+    const message = (await res.json()) as Message;
+    return { cancelRequested: message.cancelRequestedAt != null };
+  }
+
+  async replyToMessage(
+    threadId: string,
+    messageId: string,
+    opts: ReplyOptions,
+  ): Promise<ReplyResult> {
+    const url = `${this.baseUrl}/threads/${threadId}/messages/${messageId}/reply`;
+
+    const body: Record<string, unknown> = { body: opts.body };
+    if (opts.tokens !== undefined) body.tokens = opts.tokens;
+    if (opts.costUsd !== undefined) body.costUsd = opts.costUsd;
+    if (opts.errorKind !== undefined) body.errorKind = opts.errorKind;
+    if (opts.attachmentFilename !== undefined)
+      body.attachmentFilename = opts.attachmentFilename;
+    if (opts.attachmentSize !== undefined)
+      body.attachmentSize = opts.attachmentSize;
+    if (opts.attachmentBytes !== undefined)
+      body.attachmentBytes = Buffer.from(opts.attachmentBytes).toString(
+        "base64",
+      );
+
+    const res = await this.fetchFn(url, {
+      method: "POST",
+      headers: this.authHeaders(),
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      throw new ChatServiceClientError(
+        res.status,
+        `POST /threads/${threadId}/messages/${messageId}/reply failed: ${res.status}`,
+      );
+    }
+
+    return res.json() as Promise<ReplyResult>;
+  }
+
+  async getAttachment(
+    threadId: string,
+    messageId: string,
+  ): Promise<Uint8Array | null> {
+    const url = `${this.baseUrl}/threads/${threadId}/messages/${messageId}/attachment`;
+
+    const res = await this.fetchFn(url, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${this.token}` },
+    });
+
+    // 404 = no attachment — not an error, nothing to pull.
+    if (res.status === 404) {
+      return null;
+    }
+
+    if (!res.ok) {
+      throw new ChatServiceClientError(
+        res.status,
+        `GET /threads/${threadId}/messages/${messageId}/attachment failed: ${res.status}`,
+      );
+    }
+
+    return new Uint8Array(await res.arrayBuffer());
+  }
+}