@app-vitals/agent-lib 0.1.0 → 0.1.1

package/chat-notify.ts

@@ -0,0 +1,41 @@
+/**
+ * lib/chat-notify.ts
+ * Shared type for the chat service's outbound reply-notification webhook
+ * (CFB-4.3) — imported by both the chat service (builds/sends the event) and,
+ * potentially, the admin service (receives it at POST /admin/push/notify).
+ *
+ * Deliberately text-free: no message body/preview field. The payload is just
+ * enough for the admin side to look up subscriptions and render a generic
+ * "your agent replied" notification — the opt-in preview text (if any) is
+ * fetched separately by admin from the message itself, not carried here.
+ */
+
+/** Event fired once per newly-persisted agent reply. */
+export interface ReplyNotificationEvent {
+  threadId: string;
+  agentId: string;
+  /** Thread title, or null when the thread has none. Never coerced to "". */
+  title: string | null;
+}
+
+/**
+ * Parses `v` as a ReplyNotificationEvent, returning null on any shape
+ * mismatch (missing/wrong-typed fields). Used by callers that receive this
+ * payload over the wire and need to validate it before trusting the shape.
+ */
+export function parseReplyNotificationEvent(
+  v: unknown,
+): ReplyNotificationEvent | null {
+  if (typeof v !== "object" || v === null) return null;
+  const obj = v as Record<string, unknown>;
+
+  if (typeof obj.threadId !== "string") return null;
+  if (typeof obj.agentId !== "string") return null;
+  if (typeof obj.title !== "string" && obj.title !== null) return null;
+
+  return {
+    threadId: obj.threadId,
+    agentId: obj.agentId,
+    title: obj.title,
+  };
+}

package/chat-notify.unit.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from "bun:test";
+import {
+  type ReplyNotificationEvent,
+  parseReplyNotificationEvent,
+} from "./chat-notify.ts";
+
+describe("parseReplyNotificationEvent — valid shapes", () => {
+  test("parses a full event with a string title", () => {
+    const input = { threadId: "thread-1", agentId: "agent-1", title: "Hi" };
+    const result = parseReplyNotificationEvent(input);
+    expect(result).toEqual({
+      threadId: "thread-1",
+      agentId: "agent-1",
+      title: "Hi",
+    } satisfies ReplyNotificationEvent);
+  });
+
+  test("parses an event with a null title", () => {
+    const input = { threadId: "thread-1", agentId: "agent-1", title: null };
+    const result = parseReplyNotificationEvent(input);
+    expect(result).toEqual({
+      threadId: "thread-1",
+      agentId: "agent-1",
+      title: null,
+    });
+  });
+});
+
+describe("parseReplyNotificationEvent — invalid shapes", () => {
+  test("rejects null", () => {
+    expect(parseReplyNotificationEvent(null)).toBeNull();
+  });
+
+  test("rejects a non-object", () => {
+    expect(parseReplyNotificationEvent("not an object")).toBeNull();
+  });
+
+  test("rejects a missing threadId", () => {
+    expect(
+      parseReplyNotificationEvent({ agentId: "agent-1", title: null }),
+    ).toBeNull();
+  });
+
+  test("rejects a missing agentId", () => {
+    expect(
+      parseReplyNotificationEvent({ threadId: "thread-1", title: null }),
+    ).toBeNull();
+  });
+
+  test("rejects a non-string threadId", () => {
+    expect(
+      parseReplyNotificationEvent({
+        threadId: 123,
+        agentId: "agent-1",
+        title: null,
+      }),
+    ).toBeNull();
+  });
+
+  test("rejects a non-string agentId", () => {
+    expect(
+      parseReplyNotificationEvent({
+        threadId: "thread-1",
+        agentId: 123,
+        title: null,
+      }),
+    ).toBeNull();
+  });
+
+  test("rejects a non-string, non-null title", () => {
+    expect(
+      parseReplyNotificationEvent({
+        threadId: "thread-1",
+        agentId: "agent-1",
+        title: 42,
+      }),
+    ).toBeNull();
+  });
+
+  test("rejects a missing title field", () => {
+    expect(
+      parseReplyNotificationEvent({
+        threadId: "thread-1",
+        agentId: "agent-1",
+      }),
+    ).toBeNull();
+  });
+});

package/claim-ttl.ts

@@ -0,0 +1,12 @@
+import { DEFAULT_CLAUDE_TIMEOUT_MS } from "./claude-timeout.ts";
+
+/** Extra headroom added on top of the session timeout (5min). */
+export const CLAIM_TTL_BUFFER_MS = 300_000;
+
+/**
+ * Default claim TTL: how long a claim (Task or PR review/patch/deploy) remains
+ * valid without a heartbeat before it's eligible for reaping. Must exceed
+ * DEFAULT_CLAUDE_TIMEOUT_MS so a claim isn't reaped mid-session.
+ */
+export const DEFAULT_CLAIM_TTL_MS =
+  DEFAULT_CLAUDE_TIMEOUT_MS + CLAIM_TTL_BUFFER_MS;

package/claim-ttl.unit.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from "bun:test";
+import { CLAIM_TTL_BUFFER_MS, DEFAULT_CLAIM_TTL_MS } from "./claim-ttl.ts";
+import { DEFAULT_CLAUDE_TIMEOUT_MS } from "./claude-timeout.ts";
+
+describe("claim-ttl constants", () => {
+  test("CLAIM_TTL_BUFFER_MS is 300_000 (5min)", () => {
+    expect(CLAIM_TTL_BUFFER_MS).toBe(300_000);
+  });
+
+  test("DEFAULT_CLAIM_TTL_MS is 3_900_000 (65min)", () => {
+    expect(DEFAULT_CLAIM_TTL_MS).toBe(3_900_000);
+  });
+
+  test("DEFAULT_CLAIM_TTL_MS is computed as the sum of the other two constants", () => {
+    expect(DEFAULT_CLAIM_TTL_MS).toBe(
+      DEFAULT_CLAUDE_TIMEOUT_MS + CLAIM_TTL_BUFFER_MS,
+    );
+  });
+
+  // Relocated from claude-timeout.unit.test.ts (AEP-4.1): claim-ttl is the
+  // task-store side, so the cross-module invariant belongs here and the
+  // platform-set lib test no longer imports it.
+  test("DEFAULT_CLAIM_TTL_MS exceeds DEFAULT_CLAUDE_TIMEOUT_MS", () => {
+    expect(DEFAULT_CLAIM_TTL_MS).toBeGreaterThan(DEFAULT_CLAUDE_TIMEOUT_MS);
+  });
+});

package/default-account.ts

@@ -0,0 +1,5 @@
+/**
+ * The account every pre-multi-tenancy task-store row belongs to. Never use
+ * NULL for task-store accountId — the column is NOT NULL DEFAULT 'default'.
+ */
+export const DEFAULT_ACCOUNT_ID = "default";

package/default-account.unit.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "bun:test";
+import { DEFAULT_ACCOUNT_ID } from "./default-account.ts";
+
+describe("DEFAULT_ACCOUNT_ID", () => {
+  it("is the literal 'default' matching the migration's column default", () => {
+    expect(DEFAULT_ACCOUNT_ID).toBe("default");
+  });
+});

package/http.ts

@@ -0,0 +1,14 @@
+/** Parses a request body as a JSON object, returning `{}` on any error or non-object shape. */
+export async function readJson(c: {
+  req: { json: () => Promise<unknown> };
+}): Promise<Record<string, unknown>> {
+  try {
+    const body = await c.req.json();
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+      return body as Record<string, unknown>;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}

package/http.unit.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import { readJson } from "./http.ts";
+
+describe("readJson — valid bodies", () => {
+  test("returns the parsed object when the body is a plain object", async () => {
+    const c = { req: { json: async () => ({ foo: "bar" }) } };
+    expect(await readJson(c)).toEqual({ foo: "bar" });
+  });
+
+  test("returns an empty object when the body is an empty object", async () => {
+    const c = { req: { json: async () => ({}) } };
+    expect(await readJson(c)).toEqual({});
+  });
+});
+
+describe("readJson — invalid bodies", () => {
+  test("returns {} when the body is an array", async () => {
+    const c = { req: { json: async () => [1, 2, 3] } };
+    expect(await readJson(c)).toEqual({});
+  });
+
+  test("returns {} when the body is a string primitive", async () => {
+    const c = { req: { json: async () => "not an object" } };
+    expect(await readJson(c)).toEqual({});
+  });
+
+  test("returns {} when the body is null", async () => {
+    const c = { req: { json: async () => null } };
+    expect(await readJson(c)).toEqual({});
+  });
+
+  test("returns {} when req.json() throws", async () => {
+    const c = {
+      req: {
+        json: async () => {
+          throw new Error("invalid JSON");
+        },
+      },
+    };
+    expect(await readJson(c)).toEqual({});
+  });
+});

package/package-exports.unit.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import pkg from "./package.json" with { type: "json" };
+
+describe("lib/package.json exports", () => {
+  for (const [subpath, target] of Object.entries(pkg.exports)) {
+    if (target.includes("*")) continue;
+    test(`${subpath} target exists on disk`, () => {
+      expect(existsSync(join(import.meta.dir, target))).toBe(true);
+    });
+  }
+
+  test("every non-wildcard export imports cleanly", async () => {
+    for (const [, target] of Object.entries(pkg.exports)) {
+      if (target.includes("*")) continue;
+      const mod = await import(join(import.meta.dir, target));
+      expect(typeof mod).toBe("object");
+    }
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-lib",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -13,7 +13,6 @@
   "type": "module",
   "exports": {
     "./admin-types": "./admin-types.ts",
-    "./agent-default-tools": "./agent-default-tools.ts",
     "./chat-notify": "./chat-notify.ts",
     "./claim-ttl": "./claim-ttl.ts",
     "./claude-timeout": "./claude-timeout.ts",