Skip to content

Job application tracker and AI-powered job search assistant. Helps job seekers manage their search journey with AI resume review, job matching, task logging, and application analytics, all while keeping your data private.

refactor: extract the nested generation plumbing shared by two tools

Khuram Niaz9bb4ab5474ff
diff --git a/__tests__/agentMatchJobTool.spec.ts b/__tests__/agentMatchJobTool.spec.ts
index 98e4e40..aebadae 100644
--- a/__tests__/agentMatchJobTool.spec.ts
+++ b/__tests__/agentMatchJobTool.spec.ts
@@ -53,6 +53,7 @@ const ctx = () => ({
provider: "ollama",
modelName: "qwen3.5:9b",
writer: writer as any,
+ guard: { running: false },
});
const execute = (agentTool: any, input: any) =>
diff --git a/__tests__/agentNestedGeneration.spec.ts b/__tests__/agentNestedGeneration.spec.ts
new file mode 100644
index 0000000..1b4c8d5
--- /dev/null
+++ b/__tests__/agentNestedGeneration.spec.ts
@@ -0,0 +1,135 @@
+import { runNestedGeneration } from "@/lib/agent/nestedGeneration";
+import { APP_CONSTANTS } from "@/lib/constants";
+
+const streamText = vi.fn();
+vi.mock("ai", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("ai")>();
+ return { ...actual, streamText: (...args: unknown[]) => streamText(...(args as [])) };
+});
+
+function textStreamOf(chunks: string[], finishReason: unknown = "stop") {
+ return {
+ textStream: (async function* () {
+ for (const chunk of chunks) yield chunk;
+ })(),
+ finishReason: Promise.resolve(finishReason),
+ };
+}
+
+const writer = { write: vi.fn(), merge: vi.fn(), onError: undefined };
+
+const args = () => ({
+ model: { id: "fake-model" } as any,
+ system: "SYSTEM",
+ prompt: "PROMPT",
+ temperature: 0.4,
+ numCtx: APP_CONSTANTS.AI_OLLAMA_NUM_CTX,
+ timeoutMs: 1000,
+ writer: writer as any,
+ toolCallId: "call-1",
+ guard: { running: false },
+ label: "test_tool",
+});
+
+describe("runNestedGeneration", () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ streamText.mockReturnValue(textStreamOf(["hello ", "world"]));
+ });
+
+ it("passes the five varying inputs straight through", async () => {
+ await runNestedGeneration(args());
+ const call = streamText.mock.calls[0][0];
+ expect(call.system).toBe("SYSTEM");
+ expect(call.prompt).toBe("PROMPT");
+ expect(call.temperature).toBe(0.4);
+ expect(call.providerOptions.ollama.options.num_ctx).toBe(
+ APP_CONSTANTS.AI_OLLAMA_NUM_CTX,
+ );
+ expect(call.abortSignal).toBeDefined();
+ });
+
+ // The chat loop needs think:true; a sub-call with no tools does not.
+ it("never enables the thinking channel", async () => {
+ await runNestedGeneration(args());
+ expect(streamText.mock.calls[0][0].providerOptions.ollama.think).toBeUndefined();
+ });
+
+ it("returns the concatenated text on a clean finish", async () => {
+ const result = await runNestedGeneration(args());
+ expect(result).toEqual({ status: "ok", text: "hello world" });
+ });
+
+ it("writes each delta as a transient part keyed by the tool call", async () => {
+ await runNestedGeneration(args());
+ expect(writer.write).toHaveBeenCalledTimes(2);
+ const first = writer.write.mock.calls[0][0];
+ expect(first.type).toBe("data-nested-stream");
+ expect(first.id).toBe("call-1");
+ expect(first.transient).toBe(true);
+ expect(first.data.delta).toBe("hello ");
+ });
+
+ it.each(["other", "length"])(
+ "reports incomplete when the stream ends with finishReason %s",
+ async (finishReason) => {
+ streamText.mockReturnValue(textStreamOf(["partial"], finishReason));
+ const result = await runNestedGeneration(args());
+ expect(result).toEqual({ status: "incomplete" });
+ },
+ );
+
+ // A rejected finishReason throws into the catch, so an abort lands on
+ // "failed", not "incomplete". Do not "fix" this to match the other case.
+ it("reports failed when the sub-call is aborted", async () => {
+ const abortError = Object.assign(new Error("aborted"), { name: "AbortError" });
+ const rejected = Promise.reject(abortError);
+ rejected.catch(() => {});
+ streamText.mockReturnValue({
+ textStream: (async function* () {
+ yield "partial";
+ })(),
+ finishReason: rejected,
+ });
+ const result = await runNestedGeneration(args());
+ expect(result).toEqual({ status: "failed" });
+ });
+
+ it("reports failed rather than throwing when the stream errors", async () => {
+ streamText.mockReturnValue({
+ textStream: (async function* () {
+ throw new Error("connect ECONNREFUSED 127.0.0.1:11434");
+ })(),
+ });
+ const result = await runNestedGeneration(args());
+ expect(result).toEqual({ status: "failed" });
+ });
+
+ // Two nested generations in one turn serialize on Ollama to ~360s against a
+ // 300s deadline, so the second must be refused rather than started.
+ it("refuses a second generation while one is already running", async () => {
+ const guard = { running: true };
+ const result = await runNestedGeneration({ ...args(), guard });
+ expect(result).toEqual({ status: "busy" });
+ expect(streamText).not.toHaveBeenCalled();
+ });
+
+ it("releases the guard so a later generation can run", async () => {
+ const guard = { running: false };
+ await runNestedGeneration({ ...args(), guard });
+ expect(guard.running).toBe(false);
+ const second = await runNestedGeneration({ ...args(), guard });
+ expect(second.status).toBe("ok");
+ });
+
+ it("releases the guard even when the generation throws", async () => {
+ const guard = { running: false };
+ streamText.mockReturnValue({
+ textStream: (async function* () {
+ throw new Error("boom");
+ })(),
+ });
+ await runNestedGeneration({ ...args(), guard });
+ expect(guard.running).toBe(false);
+ });
+});
diff --git a/__tests__/agentReviewResumeTool.spec.ts b/__tests__/agentReviewResumeTool.spec.ts
index 53159dc..c2e3c29 100644
--- a/__tests__/agentReviewResumeTool.spec.ts
+++ b/__tests__/agentReviewResumeTool.spec.ts
@@ -49,6 +49,7 @@ const ctx = () => ({
provider: "ollama",
modelName: "qwen3.5:9b",
writer: writer as any,
+ guard: { running: false },
});
const execute = (agentTool: any, input: any) =>
diff --git a/src/lib/agent/nestedGeneration.ts b/src/lib/agent/nestedGeneration.ts
new file mode 100644
index 0000000..9061599
--- /dev/null
+++ b/src/lib/agent/nestedGeneration.ts
@@ -0,0 +1,96 @@
+import "server-only";
+
+import { streamText, type LanguageModel, type UIMessageStreamWriter } from "ai";
+import { AGENT_NESTED_STREAM_PART_TYPE } from "@/models/agent.model";
+
+export type NestedGenerationResult =
+ | { status: "ok"; text: string }
+ | { status: "incomplete" }
+ | { status: "busy" }
+ | { status: "failed" };
+
+// One per request, created in buildAgentTools. Process-wide state would block
+// one user behind another's generation.
+export type NestedGenerationGuard = { running: boolean };
+
+type NestedGenerationArgs = {
+ model: LanguageModel;
+ system: string;
+ prompt: string;
+ temperature: number;
+ numCtx: number;
+ timeoutMs: number;
+ writer: UIMessageStreamWriter;
+ toolCallId: string;
+ abortSignal?: AbortSignal;
+ guard: NestedGenerationGuard;
+ label: string;
+};
+
+/**
+ * The invariant half of an agent-as-tool: run a second generation with its own
+ * context window, stream its tokens to the transcript, and report whether it
+ * finished. Callers own everything that differs in KIND — ownership,
+ * preprocessing, parsing, saving, and the tool's result shape.
+ */
+export async function runNestedGeneration({
+ model,
+ system,
+ prompt,
+ temperature,
+ numCtx,
+ timeoutMs,
+ writer,
+ toolCallId,
+ abortSignal,
+ guard,
+ label,
+}: NestedGenerationArgs): Promise<NestedGenerationResult> {
+ // Terminal tools stop the loop after a step, not within one: the model can
+ // still emit both nested tools in a single step, and two 180s sub-calls
+ // serialize on Ollama past the 300s turn deadline, losing both.
+ if (guard.running) return { status: "busy" };
+ guard.running = true;
+
+ // Own deadline, plus the outer turn's signal so closing the panel aborts
+ // this too.
+ const signals: AbortSignal[] = [AbortSignal.timeout(timeoutMs)];
+ if (abortSignal) signals.push(abortSignal);
+
+ let text = "";
+ try {
+ const sub = streamText({
+ model,
+ system,
+ prompt,
+ temperature,
+ abortSignal: AbortSignal.any(signals),
+ // Deliberately no think:true. These sub-calls have no tools, so
+ // reasoning buys nothing and costs 30s. The chat loop enables it.
+ providerOptions: { ollama: { options: { num_ctx: numCtx } } },
+ });
+
+ for await (const delta of sub.textStream) {
+ text += delta;
+ writer.write({
+ type: AGENT_NESTED_STREAM_PART_TYPE,
+ id: toolCallId,
+ data: { delta },
+ transient: true,
+ });
+ }
+
+ // The stream running out is not the generation finishing, and neither
+ // case throws: an abort ends textStream cleanly and rejects this promise,
+ // and a body that stops without Ollama's done chunk resolves to "other".
+ const finishReason = await sub.finishReason;
+ if (finishReason !== "stop") return { status: "incomplete" };
+ } catch (error) {
+ console.error(`[agent-chat] ${label} generation failed:`, error);
+ return { status: "failed" };
+ } finally {
+ guard.running = false;
+ }
+
+ return { status: "ok", text };
+}
diff --git a/src/lib/agent/tools/index.ts b/src/lib/agent/tools/index.ts
index 36ba031..757cf66 100644
--- a/src/lib/agent/tools/index.ts
+++ b/src/lib/agent/tools/index.ts
@@ -1,5 +1,6 @@
import type { LanguageModel, ToolSet, UIMessageStreamWriter } from "ai";
import type { PageContext } from "@/models/agent.model";
+import type { NestedGenerationGuard } from "@/lib/agent/nestedGeneration";
import { buildAddJobTool } from "./addJob";
import { buildGetResumeTool } from "./getResume";
import { buildReviewResumeTool } from "./reviewResume";
@@ -18,6 +19,10 @@ export function buildAgentTools(ctx: {
modelName: string;
writer: UIMessageStreamWriter;
}): ToolSet {
+ // One per request, so the two nested tools cannot run at once but two users
+ // never block each other.
+ const nestedGuard: NestedGenerationGuard = { running: false };
+
return {
add_job: buildAddJobTool(ctx.userId, ctx.pastedText),
get_resume: buildGetResumeTool(ctx.userId, ctx.pageContext?.resumeId),
@@ -28,6 +33,7 @@ export function buildAgentTools(ctx: {
provider: ctx.provider,
modelName: ctx.modelName,
writer: ctx.writer,
+ guard: nestedGuard,
}),
match_job: buildMatchJobTool({
userId: ctx.userId,
@@ -36,6 +42,7 @@ export function buildAgentTools(ctx: {
provider: ctx.provider,
modelName: ctx.modelName,
writer: ctx.writer,
+ guard: nestedGuard,
}),
};
}
diff --git a/src/lib/agent/tools/matchJob.ts b/src/lib/agent/tools/matchJob.ts
index 8fc1d34..911f056 100644
--- a/src/lib/agent/tools/matchJob.ts
+++ b/src/lib/agent/tools/matchJob.ts
@@ -1,6 +1,6 @@
import "server-only";
-import { streamText, tool, type LanguageModel, type UIMessageStreamWriter } from "ai";
+import { tool, type LanguageModel, type UIMessageStreamWriter } from "ai";
import { TEMPERATURES } from "@/lib/ai/config";
import { APP_CONSTANTS } from "@/lib/constants";
import { AGENT_TOOL_DESCRIPTIONS } from "@/lib/agent/prompt";
@@ -15,7 +15,10 @@ import {
} from "@/lib/ai/prompts/job-match";
import { parseJobMatch } from "@/lib/ai/jobMatch/parse";
import { saveJobMatchResult } from "@/actions/job.actions";
-import { AGENT_NESTED_STREAM_PART_TYPE } from "@/models/agent.model";
+import {
+ runNestedGeneration,
+ type NestedGenerationGuard,
+} from "@/lib/agent/nestedGeneration";
import type { AgentMatchJobResult } from "@/models/agent.model";
import type { JobMatchData } from "@/models/ai.schemas";
@@ -26,6 +29,7 @@ type MatchJobContext = {
provider: string;
modelName: string;
writer: UIMessageStreamWriter;
+ guard: NestedGenerationGuard;
};
/**
@@ -81,54 +85,37 @@ export function buildMatchJobTool(ctx: MatchJobContext) {
};
}
- // Own deadline, plus the outer turn's signal so closing the panel
- // aborts this too.
- const signals: AbortSignal[] = [
- AbortSignal.timeout(APP_CONSTANTS.AI_JOB_MATCH_TIMEOUT_MS),
- ];
- if (abortSignal) signals.push(abortSignal);
-
- let generated = "";
- try {
- const sub = streamText({
- model: ctx.model,
- system: JOB_MATCH_SYSTEM_PROMPT,
- prompt: buildJobMatchPrompt(
- resumePre.data.normalizedText,
- jobPre.data.normalizedText,
- ),
- temperature: TEMPERATURES.FEEDBACK,
- abortSignal: AbortSignal.any(signals),
- // Deliberately no think:true — no tools here, so reasoning buys
- // nothing and costs 30s. The chat loop enables it; this does not.
- providerOptions: {
- ollama: { options: { num_ctx: APP_CONSTANTS.AI_OLLAMA_NUM_CTX } },
- },
- });
-
- for await (const delta of sub.textStream) {
- generated += delta;
- ctx.writer.write({
- type: AGENT_NESTED_STREAM_PART_TYPE,
- id: toolCallId,
- data: { delta },
- transient: true,
- });
- }
-
- // The stream running out is not the generation finishing, and neither
- // case throws: an abort ends textStream cleanly and rejects this, and
- // a body that stops without Ollama's done chunk resolves to "other".
- const finishReason = await sub.finishReason;
- if (finishReason !== "stop") {
- return {
- status: "generation_failed",
- jobTitle,
- reason: "The analysis stopped before it finished, so nothing was saved.",
- };
- }
- } catch (error) {
- console.error("[agent-chat] match_job generation failed:", error);
+ const generation = await runNestedGeneration({
+ model: ctx.model,
+ system: JOB_MATCH_SYSTEM_PROMPT,
+ prompt: buildJobMatchPrompt(
+ resumePre.data.normalizedText,
+ jobPre.data.normalizedText,
+ ),
+ temperature: TEMPERATURES.FEEDBACK,
+ numCtx: APP_CONSTANTS.AI_OLLAMA_NUM_CTX,
+ timeoutMs: APP_CONSTANTS.AI_JOB_MATCH_TIMEOUT_MS,
+ writer: ctx.writer,
+ toolCallId,
+ abortSignal,
+ guard: ctx.guard,
+ label: "match_job",
+ });
+ if (generation.status === "busy") {
+ return {
+ status: "generation_failed",
+ jobTitle,
+ reason: "Another analysis is already running — ask for this one once it finishes.",
+ };
+ }
+ if (generation.status === "incomplete") {
+ return {
+ status: "generation_failed",
+ jobTitle,
+ reason: "The analysis stopped before it finished, so nothing was saved.",
+ };
+ }
+ if (generation.status === "failed") {
return {
status: "generation_failed",
jobTitle,
@@ -136,7 +123,7 @@ export function buildMatchJobTool(ctx: MatchJobContext) {
};
}
- const { scores, body } = parseJobMatch(generated);
+ const { scores, body } = parseJobMatch(generation.text);
// matchData is overwrite-only with no history, so an unscored or
// half-finished generation must not be written.
if (!scores) {
diff --git a/src/lib/agent/tools/reviewResume.ts b/src/lib/agent/tools/reviewResume.ts
index a69a011..d412051 100644
--- a/src/lib/agent/tools/reviewResume.ts
+++ b/src/lib/agent/tools/reviewResume.ts
@@ -1,6 +1,6 @@
import "server-only";
-import { streamText, tool, type LanguageModel, type UIMessageStreamWriter } from "ai";
+import { tool, type LanguageModel, type UIMessageStreamWriter } from "ai";
import { TEMPERATURES } from "@/lib/ai/config";
import { APP_CONSTANTS } from "@/lib/constants";
import { AGENT_TOOL_DESCRIPTIONS } from "@/lib/agent/prompt";
@@ -13,7 +13,10 @@ import {
} from "@/lib/ai/prompts/resume-review";
import { parseResumeReview } from "@/lib/ai/resumeReview/parse";
import { saveResumeReviewResult } from "@/actions/profile.actions";
-import { AGENT_NESTED_STREAM_PART_TYPE } from "@/models/agent.model";
+import {
+ runNestedGeneration,
+ type NestedGenerationGuard,
+} from "@/lib/agent/nestedGeneration";
import type { AgentReviewResumeResult } from "@/models/agent.model";
import type { ResumeReviewData } from "@/models/ai.schemas";
@@ -24,6 +27,7 @@ type ReviewResumeContext = {
provider: string;
modelName: string;
writer: UIMessageStreamWriter;
+ guard: NestedGenerationGuard;
};
/**
@@ -60,54 +64,34 @@ export function buildReviewResumeTool(ctx: ReviewResumeContext) {
};
}
- // Own deadline, plus the outer turn's signal so closing the panel
- // aborts this too.
- const signals: AbortSignal[] = [
- AbortSignal.timeout(APP_CONSTANTS.AI_RESUME_REVIEW_TIMEOUT_MS),
- ];
- if (abortSignal) signals.push(abortSignal);
-
- let generated = "";
- try {
- const sub = streamText({
- model: ctx.model,
- system: RESUME_REVIEW_SYSTEM_PROMPT,
- prompt: buildResumeReviewPrompt(pre.data.normalizedText),
- temperature: TEMPERATURES.FEEDBACK,
- abortSignal: AbortSignal.any(signals),
- // Deliberately no think:true. This is a plain text generation with
- // no tools, so reasoning buys nothing and costs 30s on a call that
- // already runs 30-120s. The chat loop enables it; this does not.
- providerOptions: {
- ollama: { options: { num_ctx: APP_CONSTANTS.AI_OLLAMA_NUM_CTX } },
- },
- });
-
- for await (const delta of sub.textStream) {
- generated += delta;
- ctx.writer.write({
- type: AGENT_NESTED_STREAM_PART_TYPE,
- id: toolCallId,
- data: { delta },
- transient: true,
- });
- }
-
- // The stream running out is not the generation finishing, and neither
- // case throws: an abort (the user closing the panel) ends textStream
- // cleanly and rejects this promise, and a response body that stops
- // without Ollama's done chunk resolves it to "other". The SCORES line
- // is the first thing emitted, so both leave a fragment that parses.
- const finishReason = await sub.finishReason;
- if (finishReason !== "stop") {
- return {
- status: "generation_failed",
- title,
- reason: "The review stopped before it finished, so nothing was saved.",
- };
- }
- } catch (error) {
- console.error("[agent-chat] review_resume generation failed:", error);
+ const generation = await runNestedGeneration({
+ model: ctx.model,
+ system: RESUME_REVIEW_SYSTEM_PROMPT,
+ prompt: buildResumeReviewPrompt(pre.data.normalizedText),
+ temperature: TEMPERATURES.FEEDBACK,
+ numCtx: APP_CONSTANTS.AI_OLLAMA_NUM_CTX,
+ timeoutMs: APP_CONSTANTS.AI_RESUME_REVIEW_TIMEOUT_MS,
+ writer: ctx.writer,
+ toolCallId,
+ abortSignal,
+ guard: ctx.guard,
+ label: "review_resume",
+ });
+ if (generation.status === "busy") {
+ return {
+ status: "generation_failed",
+ title,
+ reason: "Another analysis is already running — ask for this one once it finishes.",
+ };
+ }
+ if (generation.status === "incomplete") {
+ return {
+ status: "generation_failed",
+ title,
+ reason: "The review stopped before it finished, so nothing was saved.",
+ };
+ }
+ if (generation.status === "failed") {
return {
status: "generation_failed",
title,
@@ -115,7 +99,7 @@ export function buildReviewResumeTool(ctx: ReviewResumeContext) {
};
}
- const { scores, body } = parseResumeReview(generated);
+ const { scores, body } = parseResumeReview(generation.text);
// reviewData is overwrite-only with no history, so an unscored or
// half-finished generation must not be written.
if (!scores) {