fix: store all scope experts on resolve to support delegate lookup

.changeset/fix-scope-delegate-resolution.md

@@ -0,0 +1,7 @@
+---
+"@perstack/runtime": patch
+"@perstack/installer": patch
+"perstack": patch
+---
+
+Store all experts from a published scope definition (coordinator + delegates) so delegates resolve from cache without separate API calls.

packages/installer/src/expert-resolver.ts

@@ -173,14 +173,19 @@ export async function resolveAllExperts(
         `Failed to resolve delegate "${delegateKey}": ${result.error.message}`,
       )
     }
-    const publishedExpert = result.data.data.definition.experts[delegateKey]
-    if (!publishedExpert) {
+    const allExperts = result.data.data.definition.experts
+    if (!allExperts[delegateKey]) {
       throw new PerstackError(`Expert "${delegateKey}" not found in API response`)
     }
-    experts[delegateKey] = toRuntimeExpert(delegateKey, publishedExpert)
-    for (const nestedDelegate of publishedExpert.delegates ?? []) {
-      if (!experts[nestedDelegate]) {
-        toResolve.add(nestedDelegate)
+    // Store all experts from the definition (coordinator + delegates)
+    for (const [key, expert] of Object.entries(allExperts)) {
+      if (!experts[key]) {
+        experts[key] = toRuntimeExpert(key, expert)
+        for (const nestedDelegate of expert.delegates ?? []) {
+          if (!experts[nestedDelegate]) {
+            toResolve.add(nestedDelegate)
+          }
+        }
       }
     }
   }

packages/runtime/src/helpers/resolve-expert.test.ts

@@ -35,6 +35,15 @@ mock.module("@perstack/api-client", () => ({
                       omit: [],
                     },
                   },
+                  delegates: [`@${expertKey}/delegate`],
+                  tags: [],
+                },
+                [`@${expertKey}/delegate`]: {
+                  name: "Delegate Expert",
+                  version: "1.0.0",
+                  description: "A delegate expert",
+                  instruction: "Delegate instruction",
+                  skills: {},
                   delegates: [],
                   tags: [],
                 },
@@ -107,13 +116,16 @@ describe("@perstack/runtime: resolveExpertToRun", () => {
     expect(result.skills["@perstack/base"].name).toBe("@perstack/base")
   })
 
-  it("does not mutate experts record", async () => {
+  it("populates experts record with all experts from definition", async () => {
     const experts: Record<string, Expert> = {}
     await resolveExpertToRun("remote-expert", experts, {
       perstackApiBaseUrl: "https://api.test.com",
       perstackApiKey: "test-key",
     })
-    expect(experts["remote-expert"]).toBeUndefined()
+    expect(experts["remote-expert"]).toBeDefined()
+    expect(experts["remote-expert"].name).toBe("Remote Expert")
+    expect(experts["@remote-expert/delegate"]).toBeDefined()
+    expect(experts["@remote-expert/delegate"].name).toBe("Delegate Expert")
   })
 
   it("fetches public expert from API without API key", async () => {
@@ -123,4 +135,17 @@ describe("@perstack/runtime: resolveExpertToRun", () => {
     })
     expect(result.key).toBe("published-expert")
   })
+
+  it("resolves delegate from already-populated experts without API call", async () => {
+    const experts: Record<string, Expert> = {}
+    await resolveExpertToRun("remote-expert", experts, {
+      perstackApiBaseUrl: "https://api.test.com",
+    })
+    // Delegate should already be in the experts record
+    const delegate = await resolveExpertToRun("@remote-expert/delegate", experts, {
+      perstackApiBaseUrl: "https://api.test.com",
+    })
+    expect(delegate.key).toBe("@remote-expert/delegate")
+    expect(delegate.name).toBe("Delegate Expert")
+  })
 })

packages/runtime/src/helpers/resolve-expert.ts

@@ -20,11 +20,17 @@ export async function resolveExpertToRun(
   if (!result.ok) {
     throw new PerstackError(`Failed to resolve expert "${expertKey}": ${result.error.message}`)
   }
-  const publishedExpert = result.data.data.definition.experts[expertKey]
-  if (!publishedExpert) {
+  const allExperts = result.data.data.definition.experts
+  if (!allExperts[expertKey]) {
     throw new PerstackError(`Expert "${expertKey}" not found in API response`)
   }
-  return toRuntimeExpert(expertKey, publishedExpert)
+  // Store all experts from the definition (coordinator + delegates)
+  for (const [key, expert] of Object.entries(allExperts)) {
+    if (!experts[key]) {
+      experts[key] = toRuntimeExpert(key, expert)
+    }
+  }
+  return experts[expertKey]
 }
 
 function toRuntimeExpert(