Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

fix(agent-sdk): scope recursion guard to AsyncLocalStorage, memoize SDK import (#782)

Rohit Ghumarefc068bee66c5
diff --git a/src/providers/agent-sdk.ts b/src/providers/agent-sdk.ts
index 566318d1..06d59461 100644
--- a/src/providers/agent-sdk.ts
+++ b/src/providers/agent-sdk.ts
@@ -1,8 +1,54 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
import type { MemoryProvider } from '../types.js'
+// #781: the recursion guard used to live on `process.env.AGENTMEMORY_SDK_CHILD`
+// (#181). #472 then introduced chunked summarize that runs chunks
+// concurrently in the same process via Promise.all. The first chunk
+// flipped the global env to "1" synchronously before its `await`, and
+// every sibling chunk in the same batch immediately bailed out as a
+// "child" — returning "" — so half-plus of the chunks failed to parse
+// and the summarize threw `too_many_chunks_skipped: N/N`.
+//
+// Split the guard so each concern uses the right primitive:
+//
+// - **In-process** recursion guard: AsyncLocalStorage. Scoped to the
+// async call tree of the SDK query, so concurrent siblings on the
+// same provider instance no longer see each other's marker.
+// - **Cross-process** recursion guard for hooks: still
+// `process.env.AGENTMEMORY_SDK_CHILD = "1"` around the SDK call.
+// Subprocesses spawned by `@anthropic-ai/claude-agent-sdk` inherit
+// `process.env` at spawn time, so the hook scripts (which run as
+// separate processes) still see the marker and skip their REST
+// callback to /summarize. ALS does not cross process boundaries.
+const sdkChildContext = new AsyncLocalStorage<true>()
+
+// Module-level refcount for the process.env marker. A per-call snapshot
+// races across overlapping calls: A saves prev=undef, B saves prev="1",
+// A's finally restores undef while B is still mid-flight (so any child
+// process B spawns won't inherit the marker), and B's finally restores
+// "1" — leaking the marker into the global env after the last caller.
+// Reference-count instead so only the first entrant snapshots the
+// original value and only the last exit restores it.
+let sdkActiveCount = 0
+let sdkOriginalEnv: string | undefined
+
+type ClaudeAgentSdkModule = typeof import('@anthropic-ai/claude-agent-sdk')
+
export class AgentSDKProvider implements MemoryProvider {
name = 'agent-sdk'
+ // Memoize the dynamic import so concurrent callers share one resolution
+ // instead of racing to resolve the specifier independently. Keeps the
+ // SDK out of the cold-start path for users on other providers.
+ private sdkPromise: Promise<ClaudeAgentSdkModule> | null = null
+
+ private loadSdk(): Promise<ClaudeAgentSdkModule> {
+ if (!this.sdkPromise) {
+ this.sdkPromise = import('@anthropic-ai/claude-agent-sdk')
+ }
+ return this.sdkPromise
+ }
+
async compress(systemPrompt: string, userPrompt: string): Promise<string> {
return this.query(systemPrompt, userPrompt)
}
@@ -12,48 +58,63 @@ export class AgentSDKProvider implements MemoryProvider {
}
private async query(systemPrompt: string, userPrompt: string): Promise<string> {
- if (process.env.AGENTMEMORY_SDK_CHILD === "1") {
- // We are already running inside a Claude Agent SDK-spawned session.
- // Spawning another one would let its plugin-hook-driven Stop loop
- // re-enter /agentmemory/summarize and cause unbounded recursion
- // (#149 follow-up). Degrade to empty string so callers short-circuit.
- return ""
+ // In-process recursion guard. Concurrent sibling calls (chunked
+ // summarize via Promise.all) each have their own ALS frame, so they
+ // do not poison each other.
+ if (sdkChildContext.getStore()) {
+ // We are already inside a Claude Agent SDK-spawned async call
+ // tree. Spawning another one would let its plugin-hook-driven
+ // Stop loop re-enter /agentmemory/summarize and cause unbounded
+ // recursion (#149 follow-up). Degrade to empty string so callers
+ // short-circuit. The chunk retry path in src/functions/summarize.ts
+ // treats "" as a parse failure but only the in-process re-entry
+ // path can reach this branch — legitimate concurrent siblings now
+ // run with their own ALS frames.
+ return ''
}
- // Mark any child process / SDK session spawned from here as a SDK
- // child. agentmemory hook scripts check this marker and skip their
- // REST calls to break the recursion loop. Restore the previous value
- // in `finally` so later calls in the same parent process are not
- // mis-classified as SDK children (otherwise every subsequent query
- // would short-circuit to "" above).
- const prev = process.env.AGENTMEMORY_SDK_CHILD
- process.env.AGENTMEMORY_SDK_CHILD = "1"
-
- try {
- const { query } = await import('@anthropic-ai/claude-agent-sdk')
-
- const messages = query({
- prompt: userPrompt,
- options: {
- systemPrompt,
- maxTurns: 1,
- allowedTools: [],
- },
- })
-
- let result = ''
- for await (const msg of messages) {
- if (msg.type === 'result') {
- result = (msg as any).result ?? ''
- }
+ return sdkChildContext.run(true, async () => {
+ // Mark spawned subprocesses (the SDK's underlying Claude session
+ // + its hook scripts) as SDK children via process.env. Hook scripts
+ // run in separate processes and read process.env to short-circuit
+ // their REST callbacks. Reference-counted so overlapping calls
+ // don't race each other into restoring stale values.
+ if (sdkActiveCount === 0) {
+ sdkOriginalEnv = process.env.AGENTMEMORY_SDK_CHILD
+ process.env.AGENTMEMORY_SDK_CHILD = '1'
}
- return result
- } finally {
- if (prev === undefined) {
- delete process.env.AGENTMEMORY_SDK_CHILD
- } else {
- process.env.AGENTMEMORY_SDK_CHILD = prev
+ sdkActiveCount++
+
+ try {
+ const { query } = await this.loadSdk()
+
+ const messages = query({
+ prompt: userPrompt,
+ options: {
+ systemPrompt,
+ maxTurns: 1,
+ allowedTools: [],
+ },
+ })
+
+ let result = ''
+ for await (const msg of messages) {
+ if (msg.type === 'result') {
+ result = (msg as any).result ?? ''
+ }
+ }
+ return result
+ } finally {
+ sdkActiveCount--
+ if (sdkActiveCount === 0) {
+ if (sdkOriginalEnv === undefined) {
+ delete process.env.AGENTMEMORY_SDK_CHILD
+ } else {
+ process.env.AGENTMEMORY_SDK_CHILD = sdkOriginalEnv
+ }
+ sdkOriginalEnv = undefined
+ }
}
- }
+ })
}
}
diff --git a/test/agent-sdk-provider.test.ts b/test/agent-sdk-provider.test.ts
new file mode 100644
index 00000000..bab17b9f
--- /dev/null
+++ b/test/agent-sdk-provider.test.ts
@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+// #781: concurrent siblings on the agent-sdk provider used to bail out
+// empty because the recursion guard mutated process.env synchronously
+// before the first await. With the guard scoped to AsyncLocalStorage,
+// each sibling runs in its own context and receives the real SDK result.
+
+// vi.mock is hoisted above module-scope `const`/`let`, so the factory's
+// closure can't safely reference non-hoisted bindings. Use vi.hoisted to
+// declare the mock's mutable state alongside the mock itself.
+const state = vi.hoisted(() => ({
+ queryCalls: [] as Array<{ systemPrompt: string; userPrompt: string }>,
+ mockResult: "<result>ok</result>" as
+ | string
+ | ((systemPrompt: string, userPrompt: string) => string),
+}));
+
+vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
+ query: ({
+ prompt,
+ options,
+ }: {
+ prompt: string;
+ options: { systemPrompt: string };
+ }) => {
+ state.queryCalls.push({ systemPrompt: options.systemPrompt, userPrompt: prompt });
+ async function* gen() {
+ const value =
+ typeof state.mockResult === "function"
+ ? await state.mockResult(options.systemPrompt, prompt)
+ : state.mockResult;
+ yield { type: "result", result: value } as { type: "result"; result: string };
+ }
+ return gen();
+ },
+}));
+
+import { AgentSDKProvider } from "../src/providers/agent-sdk.js";
+
+describe("AgentSDKProvider recursion guard (#781)", () => {
+ beforeEach(() => {
+ state.queryCalls.length = 0;
+ state.mockResult = "<result>ok</result>";
+ delete process.env.AGENTMEMORY_SDK_CHILD;
+ });
+
+ afterEach(() => {
+ delete process.env.AGENTMEMORY_SDK_CHILD;
+ });
+
+ it("concurrent summarize calls each return the SDK result (no empty siblings)", async () => {
+ const provider = new AgentSDKProvider();
+
+ const results = await Promise.all([
+ provider.summarize("sys", "chunk 1"),
+ provider.summarize("sys", "chunk 2"),
+ provider.summarize("sys", "chunk 3"),
+ provider.summarize("sys", "chunk 4"),
+ ]);
+
+ expect(results).toEqual([
+ "<result>ok</result>",
+ "<result>ok</result>",
+ "<result>ok</result>",
+ "<result>ok</result>",
+ ]);
+ expect(state.queryCalls.length).toBe(4);
+ expect(state.queryCalls.map((c) => c.userPrompt)).toEqual([
+ "chunk 1",
+ "chunk 2",
+ "chunk 3",
+ "chunk 4",
+ ]);
+ });
+
+ it("compress and summarize share the same guard scope without interfering", async () => {
+ const provider = new AgentSDKProvider();
+
+ const [a, b, c] = await Promise.all([
+ provider.summarize("sys", "s1"),
+ provider.compress("sys", "c1"),
+ provider.summarize("sys", "s2"),
+ ]);
+
+ expect(a).toBe("<result>ok</result>");
+ expect(b).toBe("<result>ok</result>");
+ expect(c).toBe("<result>ok</result>");
+ expect(state.queryCalls.length).toBe(3);
+ });
+
+ it("sets AGENTMEMORY_SDK_CHILD=1 while inside the SDK call (so spawned subprocesses inherit it)", async () => {
+ const provider = new AgentSDKProvider();
+ let observedEnv: string | undefined;
+
+ state.mockResult = (sysPrompt, _userPrompt) => {
+ observedEnv = process.env.AGENTMEMORY_SDK_CHILD;
+ return `<result>${sysPrompt}</result>`;
+ };
+
+ expect(process.env.AGENTMEMORY_SDK_CHILD).toBeUndefined();
+ await provider.summarize("sys", "user");
+ expect(observedEnv).toBe("1");
+ expect(process.env.AGENTMEMORY_SDK_CHILD).toBeUndefined();
+ });
+
+ it("restores AGENTMEMORY_SDK_CHILD to its prior value after the call", async () => {
+ const provider = new AgentSDKProvider();
+ process.env.AGENTMEMORY_SDK_CHILD = "prev-value";
+
+ await provider.summarize("sys", "user");
+
+ expect(process.env.AGENTMEMORY_SDK_CHILD).toBe("prev-value");
+ });
+
+ it("keeps AGENTMEMORY_SDK_CHILD=1 for the full overlap of concurrent calls", async () => {
+ const provider = new AgentSDKProvider();
+ // Allow the calls to overlap: each call records the env value it
+ // saw, then a tick later records it again. With a refcounted guard
+ // both observations on both calls should see "1"; with the old
+ // per-call snapshot one call's restore would null the env while
+ // the sibling is still mid-flight.
+ const observations: Array<{ id: string; phase: string; env: string | undefined }> = [];
+
+ state.mockResult = async (sysPrompt, _user) => {
+ observations.push({ id: sysPrompt, phase: "enter", env: process.env.AGENTMEMORY_SDK_CHILD });
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ observations.push({ id: sysPrompt, phase: "exit", env: process.env.AGENTMEMORY_SDK_CHILD });
+ return `<result>${sysPrompt}</result>`;
+ };
+
+ await Promise.all([
+ provider.summarize("a", "x"),
+ provider.summarize("b", "y"),
+ provider.summarize("c", "z"),
+ ]);
+
+ expect(observations.length).toBe(6);
+ for (const o of observations) {
+ expect(o.env).toBe("1");
+ }
+ expect(process.env.AGENTMEMORY_SDK_CHILD).toBeUndefined();
+ });
+
+ it("genuine re-entry (an inner call inside the same async tree) still degrades to empty", async () => {
+ const provider = new AgentSDKProvider();
+ let innerResult = "not-set";
+
+ state.mockResult = async (_sys, _user) => {
+ // Simulate the SDK callback re-entering the provider while the
+ // outer call is still active. The ALS frame is active here, so
+ // the inner call must return "" to break the recursion.
+ innerResult = await provider.summarize("sys-inner", "user-inner");
+ return "<result>outer</result>";
+ };
+
+ const outer = await provider.summarize("sys", "user");
+ expect(outer).toBe("<result>outer</result>");
+ expect(innerResult).toBe("");
+ });
+});