Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
import type { Mock } from "vitest";
import type { Response } from "express";
import { agentStatusController } from "../agent-status";
import { agentRequestSchema } from "../types";
import type { RequestWithAuth } from "../types";
import { getAgentJobAccess } from "../../../lib/operational-job-access";
import { getExtractV3AgentStatus } from "../../../lib/extract-v3-status";
vi.mock("../../../lib/operational-job-access", () => ({
getAgentJobAccess: vi.fn(),
}));
vi.mock("../../../lib/extract-v3-status", () => ({
getExtractV3AgentStatus: vi.fn(),
}));
describe("agentStatusController", () => {
const baseReq = {
params: { jobId: "job-123" },
auth: { team_id: "team-123" },
} as RequestWithAuth<{ jobId: string }, any, any>;
const buildRes = () =>
({
status: vi.fn().mockReturnThis(),
json: vi.fn(),
}) as unknown as Response;
beforeEach(() => {
vi.clearAllMocks();
});
it("returns model from agent options", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "success",
model: "spark-1-mini",
data: { result: "ok" },
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ model: "spark-1-mini" }),
);
});
it("defaults model to spark-1-pro when missing", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "failed",
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({
success: true,
status: "failed",
model: "spark-1-pro",
}),
);
});
it("returns effort from agent options", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "success",
model: "spark-2",
effort: "high",
data: { result: "ok" },
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ model: "spark-2", effort: "high" }),
);
});
it("leaves effort undefined when the agent options omit it", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "failed",
model: "spark-2",
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.status).toHaveBeenCalledWith(200);
const body = (res.json as Mock).mock.calls[0][0];
expect(body.model).toBe("spark-2");
expect(body.effort).toBeUndefined();
});
it("returns safe for a run that filtered its searches", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "processing",
model: "spark-2",
safe: true,
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ status: "processing", safe: true }),
);
});
it("leaves safe undefined when the run did not set it", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "success",
model: "spark-2",
data: { result: "ok" },
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect((res.json as Mock).mock.calls[0][0].safe).toBeUndefined();
});
it("returns terminal state and result metadata from extract-v3", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "success",
model: "spark-2",
effort: "medium",
data: { result: "ok" },
partial: { stale: true },
partialSchemaValid: false,
stopReason: "credit_limit_reached",
message: "Done",
threadId: "thread-123",
threadTurn: 2,
mode: "chat",
creditsUsed: 7,
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({
status: "completed",
data: { result: "ok" },
message: "Done",
threadId: "thread-123",
threadTurn: 2,
mode: "chat",
creditsUsed: 7,
}),
);
const body = (res.json as Mock).mock.calls[0][0];
expect(body).not.toHaveProperty("partial");
expect(body).not.toHaveProperty("partialSchemaValid");
expect(body).not.toHaveProperty("stopReason");
});
it("forwards a credit-limited partial without treating it as completed data", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "failed",
error: "Agent reached max credits",
data: { shouldNotAppear: true },
stopReason: "credit_limit_reached",
partial: { companies: [{ name: "Acme" }] },
partialSchemaValid: false,
model: "spark-2",
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({
status: "failed",
data: undefined,
stopReason: "credit_limit_reached",
partial: { companies: [{ name: "Acme" }] },
partialSchemaValid: false,
}),
);
});
it("does not expose a live processing checkpoint", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "processing",
data: { companies: [{ name: "Acme" }] },
partial: { companies: [{ name: "Acme" }] },
partialSchemaValid: false,
stopReason: "credit_limit_reached",
model: "spark-2",
});
const res = buildRes();
await agentStatusController(baseReq, res);
const body = (res.json as Mock).mock.calls[0][0];
expect(body.status).toBe("processing");
expect(body.data).toBeUndefined();
expect(body).not.toHaveProperty("partial");
expect(body).not.toHaveProperty("partialSchemaValid");
expect(body).not.toHaveProperty("stopReason");
});
it.each([
// python-sdk < 4.37.1 cannot parse "spark-2" and is lied to
["[email protected]", "spark-1-pro"],
["[email protected]", "spark-1-pro"],
["[email protected]", "spark-1-pro"],
// a prerelease of the fix may predate the Literal widening, so it
// gets the lie too
["[email protected]", "spark-1-pro"],
// everything else sees the real model
["[email protected]", "spark-2"],
["[email protected]", "spark-1-pro"],
["[email protected]", "spark-2"],
["[email protected]", "spark-2"],
["[email protected]", "spark-2"],
["[email protected]", "spark-2"],
["api", "spark-2"],
] as const)(
"reports a spark-2 job to %s as %s",
async (origin, expectedModel) => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
clientOrigin: origin,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "failed",
model: "spark-2",
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ model: expectedModel }),
);
},
);
it("keeps a genuine spark-1 model truthful even for old python-sdk clients", async () => {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
clientOrigin: "[email protected]",
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "failed",
model: "spark-1-mini",
});
const res = buildRes();
await agentStatusController(baseReq, res);
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ model: "spark-1-mini" }),
);
});
});
describe("agentRequestSchema model and effort resolution", () => {
const base = { prompt: "Find the pricing page" };
it.each(["spark-1-pro", "spark-1-mini", "spark-2"] as const)(
"redirects %s to spark-2 and leaves effort undefined",
model => {
const parsed = agentRequestSchema.parse({ ...base, model });
expect(parsed.model).toBe("spark-2");
expect(parsed.effort).toBeUndefined();
},
);
it.each(["low", "medium", "high"] as const)(
"resolves effort %s to spark-2 and keeps the effort",
effort => {
const parsed = agentRequestSchema.parse({ ...base, effort });
expect(parsed.model).toBe("spark-2");
expect(parsed.effort).toBe(effort);
},
);
it("accepts spark-2 with effort, keeping both", () => {
const parsed = agentRequestSchema.parse({
...base,
model: "spark-2",
effort: "high",
});
expect(parsed.model).toBe("spark-2");
expect(parsed.effort).toBe("high");
});
it.each(["spark-1-pro", "spark-1-mini"] as const)(
"accepts effort with retired preset %s, redirecting to spark-2",
model => {
const parsed = agentRequestSchema.parse({
...base,
model,
effort: "low",
});
expect(parsed.model).toBe("spark-2");
expect(parsed.effort).toBe("low");
},
);
it("defaults to spark-2 when the caller sends neither field", () => {
const parsed = agentRequestSchema.parse({ ...base });
expect(parsed.model).toBe("spark-2");
expect(parsed.effort).toBeUndefined();
});
it("rejects an unknown model name", () => {
expect(() =>
agentRequestSchema.parse({ ...base, model: "spark-9-unreleased" }),
).toThrow();
});
it("rejects an unknown effort level", () => {
expect(() =>
agentRequestSchema.parse({ ...base, effort: "extreme" }),
).toThrow();
});
});
describe("agentRequestSchema exchange.onTermsRequired", () => {
const base = { prompt: "Find the key business contact at exa.ai" };
it.each(["skip", "ask"] as const)(
"forwards onTermsRequired %s unchanged",
onTermsRequired => {
const parsed = agentRequestSchema.parse({
...base,
exchange: { onTermsRequired },
});
expect(parsed.exchange).toEqual({ onTermsRequired });
},
);
it("leaves onTermsRequired unset when omitted so the thread inherits it", () => {
const parsed = agentRequestSchema.parse({
...base,
exchange: { requireApproval: true },
});
expect(parsed.exchange).toEqual({ requireApproval: true });
expect(parsed.exchange?.onTermsRequired).toBeUndefined();
});
it("accepts onTermsRequired alongside an approve continuation", () => {
const approve = {
approvalId: "0199aaaa-0000-7000-8000-000000000000",
callIds: ["apollo"],
};
const parsed = agentRequestSchema.parse({
...base,
exchange: { onTermsRequired: "ask", approve },
});
expect(parsed.exchange).toEqual({ onTermsRequired: "ask", approve });
});
it("rejects decline.callIds: a terms offer is declined as a whole", () => {
expect(
agentRequestSchema.safeParse({
...base,
exchange: {
decline: {
approvalId: "0199aaaa-0000-7000-8000-000000000000",
callIds: ["apollo"],
},
},
}).success,
).toBe(false);
});
it.each(["fail", "accept", "auto", "", true])(
"rejects onTermsRequired %s",
onTermsRequired => {
expect(
agentRequestSchema.safeParse({
...base,
exchange: { onTermsRequired },
}).success,
).toBe(false);
},
);
it("still rejects unknown exchange fields", () => {
expect(
agentRequestSchema.safeParse({
...base,
exchange: { onTermsRequired: "ask", autoAcceptTerms: true },
}).success,
).toBe(false);
});
});
describe("agentStatusController terms-required passthrough", () => {
const req = {
params: { jobId: "job-123" },
auth: { team_id: "team-123" },
} as RequestWithAuth<{ jobId: string }, any, any>;
it("returns skippedProviders, requiresAction and a terms pending approval unchanged", async () => {
const approvalId = "0199aaaa-0000-7000-8000-000000000000";
const exchange = {
enabled: true,
requireApproval: false,
onTermsRequired: "ask",
paidCalls: 0,
creditsUsed: null,
skippedProviders: [
{
provider: "apollo",
name: "Apollo",
capability: "people/search",
adds: "verified work emails and direct phone numbers",
reason: "terms_required",
version: "F-1.0.0",
termsUrl: "https://www.firecrawl.dev/app/alexandria/apollo",
},
],
requiresAction: {
type: "accept_terms",
approvalId,
providers: [
{
provider: "apollo",
name: "Apollo",
capability: "people/search",
version: "F-1.0.0",
digest: null,
url: "https://www.firecrawl.dev/app/alexandria/apollo",
show: {
provider: "firecrawl",
capability: "terms/show",
options: { provider: "apollo" },
},
accept: {
provider: "firecrawl",
capability: "terms/accept",
options: {
provider: "apollo",
version: "F-1.0.0",
digest: null,
confirmed: true,
},
},
},
],
},
};
const pendingApproval = {
id: approvalId,
kind: "terms",
reason: "Apollo could add verified work emails.",
calls: [],
terms: [
{
provider: "apollo",
name: "Apollo",
version: "F-1.0.0",
digest: null,
url: "https://www.firecrawl.dev/app/alexandria/apollo",
},
],
resolution: null,
};
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: Date.now() + 60_000,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "success",
model: "spark-2",
exchange,
pendingApproval,
});
const res = {
status: vi.fn().mockReturnThis(),
json: vi.fn(),
} as unknown as Response;
await agentStatusController(req, res);
const body = (res.json as Mock).mock.calls[0][0];
expect(body.exchange).toEqual(exchange);
expect(body.pendingApproval).toEqual(pendingApproval);
});
describe("expiresAt for zero data retention runs", () => {
const MINUTE = 60 * 1000;
const completedAt = new Date(Date.now() - 5 * MINUTE).toISOString();
const rowExpiresAtMs = Date.now() + 23 * 60 * MINUTE;
const baseReq = {
params: { jobId: "job-123" },
auth: { team_id: "team-123" },
} as RequestWithAuth<{ jobId: string }, any, any>;
const buildRes = () =>
({
status: vi.fn().mockReturnThis(),
json: vi.fn(),
}) as unknown as Response;
function status(access: Record<string, unknown>, req = baseReq) {
(getAgentJobAccess as Mock).mockResolvedValue({
teamId: "team-123",
expiresAtMs: rowExpiresAtMs,
...access,
});
(getExtractV3AgentStatus as Mock).mockResolvedValue({
id: "job-123",
success: true,
status: "success",
completedAt,
});
const res = buildRes();
return agentStatusController(req, res).then(() => res);
}
it("reports completion plus the 15 minute tier", async () => {
const res = await status({ zeroDataRetentionMinutes: 15 });
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({
expiresAt: new Date(
Date.parse(completedAt) + 15 * MINUTE,
).toISOString(),
}),
);
});
it("keeps the retention recorded at start when the flag changed mid-run", async () => {
const res = await status({ zeroDataRetentionMinutes: 15 }, {
...baseReq,
acuc: { flags: { agentZdrRetentionMinutes: 1440 } },
} as any);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({
expiresAt: new Date(
Date.parse(completedAt) + 15 * MINUTE,
).toISOString(),
}),
);
});
it("answers 410 zdr_expired past the recorded retention", async () => {
const res = await status({ zeroDataRetentionMinutes: 1 });
expect(res.status).toHaveBeenCalledWith(410);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({ success: false, code: "zdr_expired" }),
);
});
it("keeps the access row's expiry for a legacy row with no retention", async () => {
const res = await status({});
expect(res.status).toHaveBeenCalledWith(200);
expect(res.json).toHaveBeenCalledWith(
expect.objectContaining({
expiresAt: new Date(rowExpiresAtMs).toISOString(),
}),
);
});
});
});