fix(api): require api server callbacks

tests/integration/api-recursive-org-execution.spec.ts

@@ -5,6 +5,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { createAgentToken, initializeAgentTokenSigningKey } from "../../src/main/agent-auth";
 import { createApiServer } from "../../src/main/api-server";
 import { AppDatabase } from "../../src/main/database";
+import { createTestApiServerCallbacks } from "../support/api-server-callbacks";
 
 const tempDirs: string[] = [];
 
@@ -83,7 +84,7 @@ async function createHarness() {
   });
   const run = db.runs.createRun({ companyId, taskId, agentId: ctoId, workspaceId, connectorId: "openai-codex" });
   const token = createAgentToken(ctoId, companyId, run.id);
-  const server = createApiServer(db, () => {}, () => null);
+  const server = createApiServer(db, createTestApiServerCallbacks());
   const port = await server.start();
 
   return {

tests/integration/api-run-events.spec.ts

@@ -5,6 +5,7 @@ import { afterEach, describe, expect, it } from "vitest";
 import { createAgentToken, initializeAgentTokenSigningKey } from "../../src/main/agent-auth";
 import { createApiServer } from "../../src/main/api-server";
 import { AppDatabase } from "../../src/main/database";
+import { createTestApiServerCallbacks } from "../support/api-server-callbacks";
 
 const tempDirs: string[] = [];
 
@@ -57,7 +58,7 @@ async function createHarness() {
   });
   const run = db.runs.createRun({ companyId, taskId, agentId, workspaceId, connectorId: "openai-codex" });
   const token = createAgentToken(agentId, companyId, run.id);
-  const server = createApiServer(db, () => {}, () => null);
+  const server = createApiServer(db, createTestApiServerCallbacks());
   const port = await server.start();
 
   return {

tests/integration/document-run-provenance.spec.ts

@@ -7,6 +7,7 @@ import { createApiServer } from "../../src/main/api-server";
 import { AppDatabase } from "../../src/main/database";
 import { processRunCompletion } from "../../src/main/automation/automation-run-completion";
 import { createDocumentWithLifecycle } from "../../src/main/document-lifecycle";
+import { createTestApiServerCallbacks } from "../support/api-server-callbacks";
 
 const tempDirs: string[] = [];
 
@@ -92,7 +93,7 @@ async function createHarness() {
   const token = createAgentToken(agentId, companyId, run.id);
   const silentLogger = { warn: () => {}, error: () => {} };
   const noopLifecycleProcessor = { drainForDocument: () => {} };
-  const server = createApiServer(db, () => {}, () => null, {
+  const server = createApiServer(db, createTestApiServerCallbacks({
     createDocument: (input) =>
       createDocumentWithLifecycle(
         {
@@ -107,7 +108,7 @@ async function createHarness() {
         },
         input,
       ),
-  });
+  }));
   const port = await server.start();
 
   return {

tests/support/api-server-callbacks.ts

@@ -0,0 +1,24 @@
+import type { ApiServerEventCallbacks } from "../../src/main/api-server";
+
+export function createTestApiServerCallbacks(
+  overrides: Partial<ApiServerEventCallbacks> = {},
+): ApiServerEventCallbacks {
+  return {
+    onDomainChanged: () => {},
+    onWakeAgent: () => null,
+    onTaskCreated: () => {},
+    onTaskStatusChanged: () => {},
+    onCommentPosted: () => {},
+    onApprovalCreated: () => {},
+    onApprovalResolved: () => {},
+    createDocument: () => {
+      throw new Error("createDocument test callback was not provided.");
+    },
+    onAutoAssignTask: () => null,
+    onHumanMessage: () => {},
+    injectRuntimeMessage: () => false,
+    emitEvent: () => {},
+    notify: () => {},
+    ...overrides,
+  };
+}

tests/unit/api-server-callbacks.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { createApiServer, type ApiServerEventCallbacks } from "../../src/main/api-server";
+import type { AppDatabase } from "../../src/main/database";
+import { createTestApiServerCallbacks } from "../support/api-server-callbacks";
+
+describe("api server callback contract", () => {
+  it("fails during construction when the callback object is missing", () => {
+    expect(() => {
+      createApiServer({} as AppDatabase, undefined as unknown as ApiServerEventCallbacks);
+    }).toThrow("Missing AgentApiServer callbacks.");
+  });
+
+  it("fails during construction when a required callback is missing", () => {
+    const callbacks: Partial<ApiServerEventCallbacks> = createTestApiServerCallbacks();
+    delete callbacks.onTaskCreated;
+
+    expect(() => {
+      createApiServer({} as AppDatabase, callbacks as ApiServerEventCallbacks);
+    }).toThrow("Missing AgentApiServer callback: onTaskCreated");
+  });
+
+  it("constructs the server when every callback is explicit", () => {
+    const callbacks = createTestApiServerCallbacks();
+    const server = createApiServer({} as AppDatabase, callbacks);
+
+    expect(server.callbacks.onTaskCreated).toBe(callbacks.onTaskCreated);
+    expect(server.onDomainChanged).toBe(callbacks.onDomainChanged);
+    expect(server.onWakeAgent).toBe(callbacks.onWakeAgent);
+  });
+});