diff --git a/.changeset/knowledge-first-graph-grants.md b/.changeset/knowledge-first-graph-grants.md new file mode 100644 index 00000000000..4c01b51486b --- /dev/null +++ b/.changeset/knowledge-first-graph-grants.md @@ -0,0 +1,6 @@ +--- +'@mastra/core': patch +'@mastra/server': patch +--- + +Studio's Knowledge graph and explorer now show grants and scope labels from store-supplied declarations (e.g. Platform Knowledge) on the first request, not only after another call loaded them. Adds `Knowledge.resolveScopeDeclarations()`. diff --git a/packages/core/src/knowledge/index.ts b/packages/core/src/knowledge/index.ts index dead8e57c10..887c36b9e0d 100644 --- a/packages/core/src/knowledge/index.ts +++ b/packages/core/src/knowledge/index.ts @@ -171,11 +171,24 @@ export class Knowledge extends MastraBase { return this.#runtime.explainAccess(runScopes, target); } + /** + * Reads the store's scope declarations into the ones {@link scopeGrants}, {@link scopeDeclaration} + * and {@link scopeLabel} use, reusing a read from the last 30 seconds. Call it before those when + * nothing else async ran first, e.g. at the start of a browsing request. Checks nothing and grants + * nothing. + * + * @experimental + */ + async resolveScopeDeclarations(): Promise { + await this.#runtime.resolve(); + } + /** * Who the declared rules give a role on one scope: each principal scope address (bound for this * scope's params) with its strongest role, `self` rules left out. `parentAddress` is the * address of the scope page's tree parent, needed for rules that bind through `belongsTo`. Reads the - * declarations as last resolved, not storage. For browsing UIs that draw access between scopes. + * declarations as last resolved, not storage (see {@link Knowledge.resolveScopeDeclarations}). For + * browsing UIs that draw access between scopes. * * @experimental */ @@ -466,7 +479,8 @@ export class Knowledge extends MastraBase { /** * The declaration a scope page was created from, by its `declaration` key (template children * included, e.g. `account:$orgId:$accountId/internal`), for display. Access rules are left out; - * use `explainAccess` for those. `undefined` for an unknown key. + * use `explainAccess` for those. `undefined` for an unknown key. Reads the declarations as last + * resolved, not storage; see {@link Knowledge.resolveScopeDeclarations}. */ scopeDeclaration(key: string): KnowledgeScopeDeclarationInfo | undefined { const compiled = this.#runtime.compiled.declarations.get(key); @@ -491,6 +505,7 @@ export class Knowledge extends MastraBase { * declaration's `$params` filled in from the address's decoded values: `'$orgId policy'` on * `policy:$orgId` gives `'acme policy'` for `policy:acme`. A concrete address's own `displayLabel` * wins over its pattern's. `undefined` when the address matches no declaration or has no label. + * Reads the declarations as last resolved, like {@link Knowledge.scopeDeclaration}. */ scopeLabel(address: string): string | undefined { const match = this.#runtime.compiled.match(address); diff --git a/packages/server/src/server/handlers/knowledge.test.ts b/packages/server/src/server/handlers/knowledge.test.ts index 3aff401f9a7..fd7efef4d66 100644 --- a/packages/server/src/server/handlers/knowledge.test.ts +++ b/packages/server/src/server/handlers/knowledge.test.ts @@ -179,6 +179,33 @@ describe('Knowledge read routes', () => { expect(graph.grants).toHaveLength(4); }); + it("sends the store's declared grants and labels on the first request, before anything else resolved them", async () => { + const { mastra, support, eng } = await setup(); + const store = await mastra.getKnowledge('main')!.getStorage(); + vi.spyOn(store, 'getScopeDeclarations').mockResolvedValue({ + ...declarations, + 'org:$orgId': { displayLabel: '$orgId organization' }, + }); + const graph = await call(GET_KNOWLEDGE_GRAPH_ROUTE, { mastra, knowledgeKey: 'main' }); + expect(graph.grants).toEqual( + expect.arrayContaining([ + { principal: 'role:acme:admin', principalLabel: 'acme admin', target: support.id, role: 'owner' }, + { principal: 'role:acme:admin', principalLabel: 'acme admin', target: eng.id, role: 'owner' }, + ]), + ); + expect(graph.grants).toHaveLength(4); + }); + + it("labels scope pages from the store's declarations on the first tree request", async () => { + const { mastra } = await setup(); + const store = await mastra.getKnowledge('main')!.getStorage(); + vi.spyOn(store, 'getScopeDeclarations').mockResolvedValue({ + 'org:$orgId': { displayLabel: '$orgId organization' }, + }); + const tree = await call(GET_KNOWLEDGE_TREE_ROUTE, { mastra, knowledgeKey: 'main' }); + expect(tree.pages.map((page: { displayLabel?: string }) => page.displayLabel)).toEqual(['acme organization']); + }); + it('sends a signed-in caller only grants from principal scopes it can read', async () => { const { mastra, acme, support } = await setup(declarations); const knowledge = mastra.listKnowledge().main as unknown as Record; diff --git a/packages/server/src/server/handlers/knowledge.ts b/packages/server/src/server/handlers/knowledge.ts index 6cb5801ed98..28d4f486a68 100644 --- a/packages/server/src/server/handlers/knowledge.ts +++ b/packages/server/src/server/handlers/knowledge.ts @@ -184,6 +184,9 @@ async function resolveStore( } const readers = requirePageReaders(); const read = await callerReadScope(mastra, requestContext, instance); + // `scopeGrants` and `scopeLabel` read the declarations as last resolved; this loads the store's. + // Older cores without it compile every declaration from config. + await instance.resolveScopeDeclarations?.(); return { instance, store: await instance.getStorage(), read, readers }; }