feat(context-engine): add subagent memory handoff

Author: phernandez

context-engine/basic-memory-context-engine.test.ts

@@ -35,6 +35,9 @@ describe("BasicMemoryContextEngine", () => {
     search: jest.Mock
     recentActivity: jest.Mock
     indexConversation: jest.Mock
+    writeNote: jest.Mock
+    editNote: jest.Mock
+    deleteNote: jest.Mock
   }
 
   beforeEach(() => {
@@ -56,6 +59,26 @@ describe("BasicMemoryContextEngine", () => {
         },
       ]),
       indexConversation: jest.fn().mockResolvedValue(undefined),
+      writeNote: jest.fn().mockResolvedValue({
+        title: "subagent-handoff-agent-test-subagent-child-1",
+        permalink: "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+        file_path:
+          "memory/agent/subagents/subagent-handoff-agent-test-subagent-child-1.md",
+        content: "",
+      }),
+      editNote: jest.fn().mockResolvedValue({
+        title: "subagent-handoff-agent-test-subagent-child-1",
+        permalink: "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+        file_path:
+          "memory/agent/subagents/subagent-handoff-agent-test-subagent-child-1.md",
+        operation: "append",
+      }),
+      deleteNote: jest.fn().mockResolvedValue({
+        title: "subagent-handoff-agent-test-subagent-child-1",
+        permalink: "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+        file_path:
+          "memory/agent/subagents/subagent-handoff-agent-test-subagent-child-1.md",
+      }),
     }
   })
 
@@ -207,6 +230,102 @@ describe("BasicMemoryContextEngine", () => {
     expect(second.systemPromptAddition).toBe(first.systemPromptAddition)
   })
 
+  it("creates a parent-to-child BM handoff note on subagent spawn", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await engine.bootstrap({
+      sessionId: "parent-session",
+      sessionFile: "/tmp/parent-session.jsonl",
+    })
+
+    const preparation = await engine.prepareSubagentSpawn({
+      parentSessionKey: "parent-session",
+      childSessionKey: "agent:test:subagent:child-1",
+    })
+
+    expect(preparation).toBeDefined()
+    expect(mockClient.writeNote).toHaveBeenCalledWith(
+      "subagent-handoff-agent-test-subagent-child-1",
+      expect.stringContaining("## Parent Basic Memory Context"),
+      "agent/subagents",
+    )
+  })
+
+  it("rolls back the handoff note when subagent spawn fails after preparation", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    const preparation = await engine.prepareSubagentSpawn({
+      parentSessionKey: "parent-session",
+      childSessionKey: "agent:test:subagent:child-rollback",
+    })
+
+    expect(preparation).toBeDefined()
+    await preparation?.rollback()
+
+    expect(mockClient.deleteNote).toHaveBeenCalledWith(
+      "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+    )
+  })
+
+  it("appends completion details to the handoff note when a child session completes", async () => {
+    const engine = new BasicMemoryContextEngine(
+      mockClient as unknown as BmClient,
+      makeConfig(),
+    )
+
+    await engine.prepareSubagentSpawn({
+      parentSessionKey: "parent-session",
+      childSessionKey: "agent:test:subagent:child-complete",
+    })
+
+    await engine.onSubagentEnded({
+      childSessionKey: "agent:test:subagent:child-complete",
+      reason: "completed",
+    })
+
+    expect(mockClient.editNote).toHaveBeenCalledWith(
+      "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+      "append",
+      expect.stringContaining("Reason: completed"),
+    )
+    expect(mockClient.editNote).toHaveBeenCalledWith(
+      "agent/subagents/subagent-handoff-agent-test-subagent-child-1",
+      "append",
+      expect.stringContaining("Durable conversation capture continues through the normal afterTurn path."),
+    )
+  })
+
+  it("handles deleted, released, and swept child endings without errors", async () => {
+    const reasons = ["deleted", "released", "swept"] as const
+
+    for (const reason of reasons) {
+      const engine = new BasicMemoryContextEngine(
+        mockClient as unknown as BmClient,
+        makeConfig(),
+      )
+
+      await engine.prepareSubagentSpawn({
+        parentSessionKey: "parent-session",
+        childSessionKey: `agent:test:subagent:${reason}`,
+      })
+
+      await expect(
+        engine.onSubagentEnded({
+          childSessionKey: `agent:test:subagent:${reason}`,
+          reason,
+        }),
+      ).resolves.toBeUndefined()
+    }
+
+    expect(mockClient.editNote).toHaveBeenCalledTimes(3)
+  })
+
   it("captures only the current turn after prePromptMessageCount", async () => {
     const engine = new BasicMemoryContextEngine(
       mockClient as unknown as BmClient,

context-engine/basic-memory-context-engine.ts

@@ -17,11 +17,19 @@ import { log } from "../logger.ts"
 const require = createRequire(import.meta.url)
 export const MAX_ASSEMBLE_RECALL_CHARS = 1200
 const TRUNCATED_RECALL_SUFFIX = "\n\n[Basic Memory recall truncated]"
+const SUBAGENT_HANDOFF_FOLDER = "agent/subagents"
+const MAX_SUBAGENT_RECALL_CHARS = 800
 
 interface SessionMemoryState {
   recallContext: string
 }
 
+interface SubagentHandoffState {
+  noteIdentifier: string
+  noteTitle: string
+  parentSessionKey: string
+}
+
 function boundRecallContext(context: string): string {
   if (context.length <= MAX_ASSEMBLE_RECALL_CHARS) {
     return context
@@ -37,6 +45,65 @@ function boundRecallContext(context: string): string {
   return `${trimmed}${TRUNCATED_RECALL_SUFFIX}`
 }
 
+function slugifySessionKey(sessionKey: string): string {
+  return sessionKey
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80)
+}
+
+function buildSubagentNoteTitle(childSessionKey: string): string {
+  return `subagent-handoff-${slugifySessionKey(childSessionKey)}`
+}
+
+function buildSubagentHandoffContent(params: {
+  parentSessionKey: string
+  childSessionKey: string
+  recallContext?: string
+}): string {
+  const sections = [
+    "# Subagent Handoff",
+    "",
+    "## Sessions",
+    `- Parent: ${params.parentSessionKey}`,
+    `- Child: ${params.childSessionKey}`,
+    "",
+    "## Lifecycle",
+    `- Spawned: ${new Date().toISOString()}`,
+  ]
+
+  if (params.recallContext) {
+    sections.push(
+      "",
+      "## Parent Basic Memory Context",
+      params.recallContext.slice(0, MAX_SUBAGENT_RECALL_CHARS).trimEnd(),
+    )
+  }
+
+  return sections.join("\n")
+}
+
+function buildSubagentCompletionUpdate(params: {
+  childSessionKey: string
+  reason: "deleted" | "completed" | "swept" | "released"
+}): string {
+  const statusLine =
+    params.reason === "completed"
+      ? "Child run completed. Durable conversation capture continues through the normal afterTurn path."
+      : `Child run ended with reason: ${params.reason}.`
+
+  return [
+    "",
+    "## Completion",
+    `- Child: ${params.childSessionKey}`,
+    `- Ended: ${new Date().toISOString()}`,
+    `- Reason: ${params.reason}`,
+    "",
+    statusLine,
+  ].join("\n")
+}
+
 type LegacyContextEngineModule = {
   LegacyContextEngine: new () => {
     compact(params: {
@@ -76,6 +143,7 @@ export class BasicMemoryContextEngine implements ContextEngine {
   } as const
 
   private readonly sessionState = new Map<string, SessionMemoryState>()
+  private readonly subagentState = new Map<string, SubagentHandoffState>()
   private legacyContextEnginePromise:
     | Promise<InstanceType<LegacyContextEngineModule["LegacyContextEngine"]>>
     | null = null
@@ -179,8 +247,73 @@ export class BasicMemoryContextEngine implements ContextEngine {
     return legacy.compact(params)
   }
 
+  async prepareSubagentSpawn(params: {
+    parentSessionKey: string
+    childSessionKey: string
+    ttlMs?: number
+  }): Promise<{ rollback: () => Promise<void> } | undefined> {
+    const parentState = this.sessionState.get(params.parentSessionKey)
+    const noteTitle = buildSubagentNoteTitle(params.childSessionKey)
+
+    try {
+      const note = await this.client.writeNote(
+        noteTitle,
+        buildSubagentHandoffContent({
+          parentSessionKey: params.parentSessionKey,
+          childSessionKey: params.childSessionKey,
+          recallContext: parentState?.recallContext,
+        }),
+        SUBAGENT_HANDOFF_FOLDER,
+      )
+
+      this.subagentState.set(params.childSessionKey, {
+        noteIdentifier: note.permalink,
+        noteTitle: note.title,
+        parentSessionKey: params.parentSessionKey,
+      })
+
+      return {
+        rollback: async () => {
+          const handoff = this.subagentState.get(params.childSessionKey)
+          this.subagentState.delete(params.childSessionKey)
+          if (!handoff) return
+
+          try {
+            await this.client.deleteNote(handoff.noteIdentifier)
+          } catch (err) {
+            log.error("context-engine subagent rollback failed", err)
+          }
+        },
+      }
+    } catch (err) {
+      log.error("context-engine prepareSubagentSpawn failed", err)
+      return undefined
+    }
+  }
+
+  async onSubagentEnded(params: {
+    childSessionKey: string
+    reason: "deleted" | "completed" | "swept" | "released"
+  }): Promise<void> {
+    const handoff = this.subagentState.get(params.childSessionKey)
+    if (!handoff) return
+
+    this.subagentState.delete(params.childSessionKey)
+
+    try {
+      await this.client.editNote(
+        handoff.noteIdentifier,
+        "append",
+        buildSubagentCompletionUpdate(params),
+      )
+    } catch (err) {
+      log.error("context-engine onSubagentEnded failed", err)
+    }
+  }
+
   async dispose(): Promise<void> {
     this.sessionState.clear()
+    this.subagentState.clear()
   }
 
   private async getLegacyContextEngine(): Promise<