@mastra/factory 0.21.0-alpha.3 → 0.21.0-alpha.4

package/dist/routes/knowledge.js

@@ -1,6 +1,6 @@
 import { Route } from "./route.js";
 import { registerApiRoute } from "@mastra/core/server";
-import { canonicalizeKnowledgeScope, isKnowledgeScopeVisible, knowledgeScopeKey, parseKnowledgeWikilinks } from "@mastra/core/storage";
+import { KnowledgeUnsupportedCapabilityError, canonicalizeKnowledgeScope, isKnowledgeScopeVisible, knowledgeScopeKey, parseKnowledgeWikilinks } from "@mastra/core/storage";
 //#region src/routes/knowledge.ts
 /** Reserved node that anchors pinned records (see subconscious/pinned.ts). */
 const PINNED_NODE_NAME = "pinned";
@@ -10,10 +10,27 @@ function truncateRecordText(text) {
 	return text.length > RECORD_TEXT_LIMIT ? `${text.slice(0, RECORD_TEXT_LIMIT - 1)}…` : text;
 }
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Authorized visible events returned per activity page. */
+const ACTIVITY_PAGE_SIZE = 25;
+/** Events fetched per `listActivity` batch while filling a visible page. */
+const ACTIVITY_BATCH = 100;
+/** Hard scan cap so a huge hidden backlog cannot spin the request. */
+const ACTIVITY_SCAN_CAP = 1e3;
+/** Maximum visible nodes inspected for non-prefix name matches. */
+const SEARCH_SCAN_CAP = 1e3;
+/** Compact result window returned to the search popover. */
+const SEARCH_RESULT_LIMIT = 20;
+/** Prevent an unbounded query string from reaching storage. */
+const SEARCH_QUERY_LIMIT = 128;
+/** Scope nodes returned per parent while lazily expanding the tree. */
+const SCOPE_PAGE_SIZE = 25;
+/** Bound storage pressure while calculating direct-member counts. */
+const SCOPE_COUNT_CONCURRENCY = 8;
 const DEFAULT_LIMITS = {
 	maxNodes: 500,
 	maxRecords: 2e3,
-	maxFallbackLookups: 100
+	maxFallbackLookups: 100,
+	maxOrgScopePages: 10
 };
 function loose(c) {
 	return c;
@@ -27,6 +44,80 @@ function deepestRung(scope) {
 	}
 	return rung;
 }
+/**
+* True when `scope` is a prefix of the active view scope — the content lives
+* inside the current org + project boundary. Structural member lenses use
+* this to keep sibling-project knowledge out of a project-scoped view.
+*/
+function withinViewBoundary(scope, viewScope) {
+	return scope.length <= viewScope.length && scope.every((entry, index) => entry === viewScope[index]);
+}
+function directScopeMemberCounts({ members, hasMore }, childScopeCount, viewScope, maxNodes) {
+	const contentNodeCount = members.filter((member) => !member.isScope && Array.isArray(member.scope) && withinViewBoundary(member.scope, viewScope)).length;
+	const directMemberCount = childScopeCount + contentNodeCount;
+	return {
+		memberCount: Math.min(directMemberCount, maxNodes),
+		memberCountTruncated: directMemberCount > maxNodes || hasMore,
+		contentNodeCount,
+		childScopeCount
+	};
+}
+function compareScopeNodes(a, b) {
+	return a.name.localeCompare(b.name) || a.id.localeCompare(b.id);
+}
+/**
+* Scopes in one org (the org scope and everything beneath it), filtered and paged in storage.
+* Reads at most `maxPages` pages; `truncated` is true when scopes remain past that point.
+*/
+async function listOrgScopeNodes(store, orgId, maxPages) {
+	const scopes = [];
+	let cursor;
+	for (let page = 0; page < maxPages; page += 1) {
+		const result = await store.listScopeNodes({
+			withinAddress: `org:${orgId}`,
+			cursor
+		});
+		scopes.push(...result.scopes);
+		if (!result.nextCursor) return {
+			scopes,
+			truncated: false
+		};
+		cursor = result.nextCursor;
+	}
+	return {
+		scopes,
+		truncated: true
+	};
+}
+/** One scope node, only if it is in the org. Independent of how many scopes the org has. */
+async function findOrgScopeNode(store, orgId, scopeNodeId) {
+	const { scopes } = await store.listScopeNodes({
+		withinAddress: `org:${orgId}`,
+		ids: [scopeNodeId],
+		limit: 1
+	});
+	return scopes[0];
+}
+function knowledgeSearchRank(name, query) {
+	const normalized = name.toLocaleLowerCase();
+	if (normalized === query) return 0;
+	if (normalized.startsWith(query)) return 1;
+	return 2;
+}
+/**
+* What a scope node is, for labels: the rung name for vouched identity scopes, otherwise the
+* stored kind, or "topic" for structural scopes created without one. Matches the scope list.
+*/
+function scopeKindLabel(address, kind) {
+	if (address.startsWith("org:")) return "org";
+	if (address.startsWith("resource:")) return "project";
+	if (address.startsWith("thread:")) return "session";
+	return kind || "topic";
+}
+/** The thread id of a session (`thread:<id>`) scope node, or undefined for any other scope. */
+function sessionThreadId(node) {
+	return node.address.startsWith("thread:") ? boundedThreadId(node.address.slice(7)) : void 0;
+}
 function boundedThreadId(raw) {
 	if (!raw) return void 0;
 	const trimmed = raw.trim();
@@ -94,7 +185,9 @@ var WikilinkResolver = class {
 	#trackOutOfWindow(node) {
 		if (node && !this.#windowIds.has(node.id)) this.outOfWindow.set(node.id, {
 			id: node.id,
-			name: node.name
+			name: node.name,
+			scope: node.scope,
+			rung: deepestRung(node.scope)
 		});
 		return node;
 	}
@@ -143,14 +236,23 @@ var KnowledgeRoutes = class extends Route {
 		if (!projectId || !UUID_RE.test(projectId)) return { response: c.json({ error: "Project not found" }, 404) };
 		const { projects } = this.deps;
 		await projects.ensureReady();
-		if (!await projects.get({
+		const project = await projects.get({
 			orgId: tenant.orgId,
 			id: projectId
-		})) return { response: c.json({ error: "Project not found" }, 404) };
-		const store = await this.deps.knowledge();
-		if (!store) return { response: c.json({
+		});
+		if (!project) return { response: c.json({ error: "Project not found" }, 404) };
+		let knowledge;
+		let store;
+		try {
+			const key = this.deps.defaultKnowledgeKey ?? "default";
+			knowledge = await this.deps.knowledge(key);
+			store = knowledge ? await knowledge.getStorage() : void 0;
+		} catch {
+			store = void 0;
+		}
+		if (!store || !knowledge) return { response: c.json({
 			error: "knowledge_unavailable",
-			message: "The knowledge storage domain is not configured."
+			message: "The configured Knowledge runtime is unavailable."
 		}, 503) };
 		const defaultScope = [`org:${tenant.orgId}`, `resource:${projectId}`];
 		const resourceRungScope = defaultScope;
@@ -159,6 +261,8 @@ var KnowledgeRoutes = class extends Route {
 		if (!threadId) return {
 			...tenant,
 			factoryProjectId: projectId,
+			factoryProjectName: project.name,
+			knowledge,
 			store,
 			view: "project",
 			scope: defaultScope,
@@ -176,6 +280,8 @@ var KnowledgeRoutes = class extends Route {
 		return {
 			...tenant,
 			factoryProjectId: projectId,
+			factoryProjectName: project.name,
+			knowledge,
 			store,
 			view: "thread",
 			threadId,
@@ -189,6 +295,122 @@ var KnowledgeRoutes = class extends Route {
 			}]
 		};
 	}
+	#selectedView(view, level) {
+		const projectView = {
+			orgId: view.orgId,
+			userId: view.userId,
+			factoryProjectId: view.factoryProjectId,
+			factoryProjectName: view.factoryProjectName,
+			knowledge: view.knowledge,
+			store: view.store,
+			view: "project"
+		};
+		if (level === "org") return {
+			...projectView,
+			scope: view.scope.slice(0, 1),
+			pinRungs: []
+		};
+		if (level === "resource") return {
+			...projectView,
+			scope: view.scope.slice(0, 2),
+			pinRungs: view.pinRungs.filter((rung) => rung.rung === "resource")
+		};
+		if (level === "thread" && view.threadId) return view;
+	}
+	/**
+	* Host-vouched identity chain: the org → project → session rungs this
+	* request resolved are materialized as ordinary scope nodes linked by
+	* membership edges, so the sidebar tree is built from scopes that EXIST —
+	* never from the declared structure plan or the rung config. Materialization
+	* is create-only and deduped by address (existing nodes keep their declared
+	* names/parents), so the steady state is a no-op skip. No companion scope is
+	* created here or anywhere automatically. A vouch failure never fails the read —
+	* the tree simply serves the scopes that already exist.
+	*/
+	async #vouchIdentityScopes(view) {
+		const orgAddress = `org:${view.orgId}`;
+		const resourceAddress = `resource:${view.factoryProjectId}`;
+		const chain = [
+			{
+				address: orgAddress,
+				contextualScopeAddress: orgAddress
+			},
+			{
+				address: resourceAddress,
+				name: view.factoryProjectName,
+				contextualScopeAddress: orgAddress,
+				parentAddresses: [orgAddress]
+			},
+			...view.threadId ? [{
+				address: `thread:${view.threadId}`,
+				contextualScopeAddress: resourceAddress,
+				parentAddresses: [resourceAddress]
+			}] : []
+		];
+		let existing;
+		try {
+			const { scopes } = await view.store.listScopeNodes({ addresses: chain.map((link) => link.address) });
+			existing = new Set(scopes.map((node) => node.address));
+		} catch (error) {
+			if (error instanceof KnowledgeUnsupportedCapabilityError) return;
+			throw error;
+		}
+		for (const link of chain) {
+			if (existing.has(link.address)) continue;
+			await view.knowledge.materializeScope(link).catch(() => void 0);
+		}
+	}
+	/**
+	* Session scopes are listed only under the viewed project, and only when the `threadId`
+	* drill-down would accept them (a visible record captured in that session), so no listing
+	* exposes a session id the drill-down would reject. Returns the ids of hidden session nodes.
+	* With `probe: false` only the cheap project check runs; callers probe the bounded page they return.
+	*/
+	async #hiddenSessionIds(view, nodes, projectNodeId, { probe }) {
+		const hidden = /* @__PURE__ */ new Set();
+		const projectScope = [`org:${view.orgId}`, `resource:${view.factoryProjectId}`];
+		const sessions = [];
+		for (const node of nodes) {
+			if (!node.address.startsWith("thread:")) continue;
+			const threadId = sessionThreadId(node);
+			if (!threadId || !projectNodeId || !node.parentIds.includes(projectNodeId)) hidden.add(node.id);
+			else if (probe && threadId !== view.threadId) sessions.push({
+				id: node.id,
+				threadId
+			});
+		}
+		for (let index = 0; index < sessions.length; index += SCOPE_COUNT_CONCURRENCY) await Promise.all(sessions.slice(index, index + SCOPE_COUNT_CONCURRENCY).map(async ({ id, threadId }) => {
+			const { records } = await view.store.knowledgeBySource({
+				sourceThreadId: threadId,
+				scope: [...projectScope, `thread:${threadId}`],
+				limit: 1
+			});
+			if (records.length === 0) hidden.add(id);
+		}));
+		return hidden;
+	}
+	/**
+	* Display names for session scopes, resolved at read time from the thread's current title
+	* (never stored on the scope node, where it would go stale). Keyed by scope node id.
+	*/
+	async #sessionNames(nodes) {
+		const names = /* @__PURE__ */ new Map();
+		const sessions = nodes.flatMap((node) => {
+			const threadId = node.address.startsWith("thread:") ? node.address.slice(7) : "";
+			return threadId ? [{
+				id: node.id,
+				threadId
+			}] : [];
+		});
+		for (let index = 0; index < sessions.length; index += SCOPE_COUNT_CONCURRENCY) await Promise.all(sessions.slice(index, index + SCOPE_COUNT_CONCURRENCY).map(async ({ id, threadId }) => {
+			let title;
+			try {
+				title = (await this.deps.threadTitle?.(threadId))?.trim();
+			} catch {}
+			names.set(id, title || `session ${threadId.slice(0, 8)}`);
+		}));
+		return names;
+	}
 	/** Reserved `pinned` node ids at the active view's rungs (one exact-scope lookup per rung). */
 	async #pinnedNodeIds(view) {
 		const out = [];
@@ -222,18 +444,383 @@ var KnowledgeRoutes = class extends Route {
 	}
 	routes() {
 		return [
-			registerApiRoute("/web/factory/projects/:id/knowledge/graph", {
+			registerApiRoute("/web/factory/projects/:id/knowledge/scopes", {
+				method: "GET",
+				requiresAuth: false,
+				handler: async (c) => {
+					const view = await this.#resolveView(loose(c));
+					if ("response" in view) return view.response;
+					await this.#vouchIdentityScopes(view);
+					let scopeNodes;
+					let nextCursor;
+					const childCursors = {};
+					let storedScopeNodes = [];
+					let scopesTruncated = false;
+					try {
+						({scopes: storedScopeNodes, truncated: scopesTruncated} = await listOrgScopeNodes(view.store, view.orgId, this.#limits.maxOrgScopePages));
+						const projectNodeId = storedScopeNodes.find((node) => node.address === `resource:${view.factoryProjectId}`)?.id;
+						const foreignSessions = await this.#hiddenSessionIds(view, storedScopeNodes, projectNodeId, { probe: false });
+						storedScopeNodes = storedScopeNodes.filter((node) => !foreignSessions.has(node.id));
+						const scopeNodeById = new Map(storedScopeNodes.map((node) => [node.id, node]));
+						const childScopeCountByParent = /* @__PURE__ */ new Map();
+						for (const node of storedScopeNodes) for (const parentId of node.parentIds) childScopeCountByParent.set(parentId, (childScopeCountByParent.get(parentId) ?? 0) + 1);
+						const parentId = loose(c).req.query("parentId");
+						const cursor = loose(c).req.query("cursor");
+						if (parentId && !UUID_RE.test(parentId)) return c.json({ error: "invalid_scope_parent" }, 400);
+						if (cursor && !UUID_RE.test(cursor)) return c.json({ error: "invalid_scope_cursor" }, 400);
+						if (parentId && !scopeNodeById.has(parentId)) return c.json({ error: "scope_not_found" }, 404);
+						const siblings = storedScopeNodes.filter((node) => parentId ? node.parentIds.includes(parentId) : node.parentIds.length === 0).sort(compareScopeNodes);
+						const cursorIndex = cursor ? siblings.findIndex((node) => node.id === cursor) : -1;
+						if (cursor && cursorIndex < 0) return c.json({ error: "invalid_scope_cursor" }, 400);
+						const pageStart = cursorIndex + 1;
+						const siblingPage = siblings.slice(pageStart, pageStart + SCOPE_PAGE_SIZE);
+						if (pageStart + siblingPage.length < siblings.length) nextCursor = siblingPage.at(-1)?.id;
+						const returnedById = new Map(siblingPage.map((node) => [node.id, node]));
+						if (!parentId) {
+							const addFirstChildPage = (parent) => {
+								const children = storedScopeNodes.filter((node) => node.parentIds.includes(parent.id)).sort(compareScopeNodes);
+								const returnedChildren = [];
+								for (const child of children.slice(0, SCOPE_PAGE_SIZE)) {
+									if (returnedById.size >= this.#limits.maxNodes) break;
+									returnedById.set(child.id, child);
+									returnedChildren.push(child);
+								}
+								if (returnedChildren.length < children.length) {
+									const lastChild = returnedChildren.at(-1);
+									if (lastChild) childCursors[parent.id] = lastChild.id;
+								}
+							};
+							for (const root of siblingPage) addFirstChildPage(root);
+							const identityAddresses = /* @__PURE__ */ new Set([
+								`org:${view.orgId}`,
+								`resource:${view.factoryProjectId}`,
+								...view.threadId ? [`thread:${view.threadId}`] : []
+							]);
+							const includeWithParents = (node) => {
+								if (returnedById.has(node.id) || returnedById.size >= this.#limits.maxNodes) return;
+								for (const ancestorId of node.parentIds) {
+									const ancestor = scopeNodeById.get(ancestorId);
+									if (ancestor) includeWithParents(ancestor);
+								}
+								returnedById.set(node.id, node);
+							};
+							for (const node of storedScopeNodes) if (identityAddresses.has(node.address)) includeWithParents(node);
+							const projectNode = projectNodeId ? scopeNodeById.get(projectNodeId) : void 0;
+							if (projectNode && returnedById.has(projectNode.id)) addFirstChildPage(projectNode);
+						}
+						const unreadableSessions = await this.#hiddenSessionIds(view, [...returnedById.values()], projectNodeId, { probe: true });
+						for (const id of unreadableSessions) returnedById.delete(id);
+						scopeNodes = [];
+						const returnedNodes = [...returnedById.values()].sort(compareScopeNodes);
+						for (let index = 0; index < returnedNodes.length; index += SCOPE_COUNT_CONCURRENCY) {
+							const batch = returnedNodes.slice(index, index + SCOPE_COUNT_CONCURRENCY);
+							scopeNodes.push(...await Promise.all(batch.map(async (node) => {
+								const members = await view.store.listScopeMembers({
+									scopeNodeId: node.id,
+									limit: this.#limits.maxNodes
+								});
+								return {
+									...node,
+									...node.address === `resource:${view.factoryProjectId}` ? { name: view.factoryProjectName } : {},
+									...directScopeMemberCounts(members, childScopeCountByParent.get(node.id) ?? 0, view.scope, this.#limits.maxNodes)
+								};
+							})));
+						}
+						const sessionNames = await this.#sessionNames(scopeNodes);
+						scopeNodes = scopeNodes.map((node) => ({
+							...node,
+							kind: scopeKindLabel(node.address, node.kind),
+							...sessionNames.has(node.id) ? { name: sessionNames.get(node.id) } : {}
+						}));
+					} catch (error) {
+						if (!(error instanceof KnowledgeUnsupportedCapabilityError)) throw error;
+						scopeNodes = void 0;
+					}
+					const scopeNodeByAddress = new Map(storedScopeNodes.map((node) => [node.address, node]));
+					const threadRoot = view.threadId ? scopeNodeByAddress.get(`thread:${view.threadId}`) : void 0;
+					const threadRootName = threadRoot ? (await this.#sessionNames([threadRoot])).get(threadRoot.id) : void 0;
+					const rungs = [
+						{
+							level: "org",
+							id: view.orgId,
+							available: true
+						},
+						{
+							level: "resource",
+							id: view.factoryProjectId,
+							available: true
+						},
+						...view.threadId ? [{
+							level: "thread",
+							id: view.threadId,
+							available: true
+						}] : []
+					];
+					return c.json({
+						roots: rungs.map((rung) => {
+							const match = scopeNodeByAddress.get(`${rung.level}:${rung.id}`);
+							const name = match?.address === `resource:${view.factoryProjectId}` ? view.factoryProjectName : match && rung.level === "thread" ? threadRootName : match?.name;
+							return match ? {
+								...rung,
+								scopeNodeId: match.id,
+								name
+							} : rung;
+						}),
+						defaultLevel: "resource",
+						...scopeNodes ? { scopeNodes } : {},
+						...nextCursor ? { nextCursor } : {},
+						...Object.keys(childCursors).length > 0 ? { childCursors } : {},
+						...scopesTruncated ? { truncated: true } : {}
+					});
+				}
+			}),
+			registerApiRoute("/web/factory/projects/:id/knowledge/search", {
 				method: "GET",
 				requiresAuth: false,
 				handler: async (c) => {
 					const view = await this.#resolveView(loose(c));
 					if ("response" in view) return view.response;
+					const query = (loose(c).req.query("q") ?? "").trim().slice(0, SEARCH_QUERY_LIMIT).toLocaleLowerCase();
+					if (query.length < 2) return c.json({
+						results: [],
+						truncated: false
+					});
+					const scanLimit = Math.min(SEARCH_SCAN_CAP, this.#limits.maxNodes);
+					const [prefixNodes, scannedNodes] = await Promise.all([view.store.listNodes({
+						scope: view.scope,
+						namePrefix: query,
+						limit: 21
+					}), view.store.listNodes({
+						scope: view.scope,
+						limit: scanLimit
+					})]);
+					const contentById = /* @__PURE__ */ new Map();
+					for (const node of [...prefixNodes, ...scannedNodes]) {
+						if (node.isScope || !Array.isArray(node.scope) || !withinViewBoundary(node.scope, view.scope) || !node.name.toLocaleLowerCase().includes(query)) continue;
+						contentById.set(node.id, node);
+					}
+					let structuralScopes = [];
+					let scopesTruncated = false;
+					try {
+						const orgScopes = await listOrgScopeNodes(view.store, view.orgId, this.#limits.maxOrgScopePages);
+						scopesTruncated = orgScopes.truncated;
+						structuralScopes = orgScopes.scopes.filter((node) => (!node.address.startsWith("thread:") || sessionThreadId(node) === view.threadId) && node.name.toLocaleLowerCase().includes(query));
+					} catch (error) {
+						if (!(error instanceof KnowledgeUnsupportedCapabilityError)) throw error;
+					}
+					const scopeSessionNames = await this.#sessionNames(structuralScopes);
+					const results = [...structuralScopes.map((scopeNode) => {
+						const rung = scopeNode.address === `org:${view.orgId}` ? "org" : scopeNode.address === `resource:${view.factoryProjectId}` ? "resource" : view.threadId && scopeNode.address === `thread:${view.threadId}` ? "thread" : null;
+						return {
+							id: scopeNode.id,
+							name: scopeNode.address === `resource:${view.factoryProjectId}` ? view.factoryProjectName : scopeSessionNames.get(scopeNode.id) ?? scopeNode.name,
+							kind: scopeKindLabel(scopeNode.address, scopeNode.kind),
+							type: "scope",
+							rung,
+							address: scopeNode.address,
+							...scopeNode.description ? { description: scopeNode.description } : {}
+						};
+					}), ...[...contentById.values()].map((node) => {
+						const rung = deepestRung(node.scope);
+						const threadId = rung === "thread" ? node.scope.find((address) => address.startsWith("thread:"))?.slice(7) : void 0;
+						return {
+							id: node.id,
+							name: node.name,
+							kind: node.kind,
+							type: "node",
+							rung,
+							...threadId ? { threadId } : {}
+						};
+					})].sort((a, b) => knowledgeSearchRank(a.name, query) - knowledgeSearchRank(b.name, query) || a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+					return c.json({
+						results: results.slice(0, SEARCH_RESULT_LIMIT),
+						truncated: scopesTruncated || results.length > SEARCH_RESULT_LIMIT || prefixNodes.length > SEARCH_RESULT_LIMIT || scannedNodes.length >= scanLimit
+					});
+				}
+			}),
+			registerApiRoute("/web/factory/projects/:id/knowledge/subgraph", {
+				method: "GET",
+				requiresAuth: false,
+				handler: async (c) => {
+					const resolved = await this.#resolveView(loose(c));
+					if ("response" in resolved) return resolved.response;
+					const scopeNodeId = loose(c).req.query("scopeNodeId");
+					if (scopeNodeId !== void 0) {
+						if (!UUID_RE.test(scopeNodeId)) return c.json({ error: "scope_not_found" }, 404);
+						const limits = this.#limits;
+						const { store } = resolved;
+						let storedRoot;
+						try {
+							storedRoot = await findOrgScopeNode(store, resolved.orgId, scopeNodeId);
+						} catch (error) {
+							if (error instanceof KnowledgeUnsupportedCapabilityError) return c.json({ error: "scope_not_found" }, 404);
+							throw error;
+						}
+						if (!storedRoot) return c.json({ error: "scope_not_found" }, 404);
+						const { scopes: scopeNodes, truncated: scopesTruncated } = await listOrgScopeNodes(store, resolved.orgId, limits.maxOrgScopePages);
+						const rootSessionName = (await this.#sessionNames([storedRoot])).get(storedRoot.id);
+						const root = storedRoot.address === `resource:${resolved.factoryProjectId}` ? {
+							...storedRoot,
+							name: resolved.factoryProjectName
+						} : rootSessionName ? {
+							...storedRoot,
+							name: rootSessionName
+						} : storedRoot;
+						if (storedRoot.address.startsWith("thread:")) {
+							const projectNodeId = scopeNodes.find((node) => node.address === `resource:${resolved.factoryProjectId}`)?.id;
+							if ((await this.#hiddenSessionIds(resolved, [storedRoot], projectNodeId, { probe: true })).has(storedRoot.id)) return c.json({ error: "scope_not_found" }, 404);
+						}
+						const otherSessionIds = new Set(scopeNodes.filter((node) => node.address.startsWith("thread:") && sessionThreadId(node) !== resolved.threadId).map((node) => node.id));
+						const fetched = await store.listScopeMembers({
+							scopeNodeId,
+							limit: limits.maxNodes
+						});
+						const bounded = fetched.members.filter((node) => node.isScope && !otherSessionIds.has(node.id) || !node.isScope && Array.isArray(node.scope) && withinViewBoundary(node.scope, resolved.scope));
+						let truncated = scopesTruncated || fetched.hasMore || bounded.length > limits.maxNodes;
+						const members = bounded.slice(0, limits.maxNodes);
+						const contentMembers = members.filter((node) => !node.isScope && Array.isArray(node.scope));
+						const childScopeCountByParent = /* @__PURE__ */ new Map();
+						for (const node of scopeNodes) for (const parentId of node.parentIds) childScopeCountByParent.set(parentId, (childScopeCountByParent.get(parentId) ?? 0) + 1);
+						const scopeCountsById = /* @__PURE__ */ new Map([[root.id, directScopeMemberCounts(fetched, childScopeCountByParent.get(root.id) ?? 0, resolved.scope, limits.maxNodes)]]);
+						const memberScopes = members.filter((node) => node.isScope);
+						for (let index = 0; index < memberScopes.length; index += SCOPE_COUNT_CONCURRENCY) {
+							const batch = memberScopes.slice(index, index + SCOPE_COUNT_CONCURRENCY);
+							await Promise.all(batch.map(async (node) => {
+								const directMembers = await store.listScopeMembers({
+									scopeNodeId: node.id,
+									limit: limits.maxNodes
+								});
+								scopeCountsById.set(node.id, directScopeMemberCounts(directMembers, childScopeCountByParent.get(node.id) ?? 0, resolved.scope, limits.maxNodes));
+							}));
+						}
+						const recordWindow = [];
+						for (const node of contentMembers) {
+							if (recordWindow.length > limits.maxRecords) break;
+							const { records } = await store.listKnowledgeAbout({
+								node: node.id,
+								scope: node.scope,
+								limit: limits.maxRecords + 1 - recordWindow.length
+							});
+							recordWindow.push(...records);
+						}
+						recordWindow.sort((a, b) => b.id.localeCompare(a.id));
+						if (recordWindow.length > limits.maxRecords) {
+							truncated = true;
+							recordWindow.length = limits.maxRecords;
+						}
+						const resolver = new WikilinkResolver(store, contentMembers, limits.maxFallbackLookups);
+						const edges = [];
+						const graphRecords = [];
+						const edgeSeen = /* @__PURE__ */ new Set();
+						const recordCounts = /* @__PURE__ */ new Map();
+						for (const record of recordWindow) {
+							recordCounts.set(record.node, (recordCounts.get(record.node) ?? 0) + 1);
+							const nodeIds = [record.node];
+							for (const name of parseKnowledgeWikilinks(record.text)) {
+								const target = await resolver.resolve(name, record.scope);
+								if (!target) continue;
+								if (target.id === record.node) continue;
+								if (!resolver.inWindowId(target.id)) continue;
+								if (!nodeIds.includes(target.id)) nodeIds.push(target.id);
+								const key = `${record.node}\u0000${target.id}`;
+								if (edgeSeen.has(key)) continue;
+								edgeSeen.add(key);
+								edges.push({
+									id: `wikilink:${record.node}:${target.id}`,
+									source: record.node,
+									target: target.id,
+									type: "wikilink",
+									recordId: record.id
+								});
+							}
+							graphRecords.push({
+								id: record.id,
+								nodeIds,
+								pinned: false,
+								text: truncateRecordText(record.text)
+							});
+						}
+						for (const member of members) edges.push({
+							id: `contains:${root.id}:${member.id}`,
+							source: root.id,
+							target: member.id,
+							type: "contains"
+						});
+						const scopeAddressById = new Map(scopeNodes.map((node) => [node.id, node.address]));
+						const memberSessionNames = await this.#sessionNames(members.flatMap((node) => {
+							const address = node.isScope ? scopeAddressById.get(node.id) : void 0;
+							return address ? [{
+								id: node.id,
+								address
+							}] : [];
+						}));
+						const rootRow = await store.getNode(root.id);
+						const activity = await store.listActivity({
+							scope: resolved.scope,
+							limit: 1
+						});
+						const payload = {
+							view: resolved.view,
+							...resolved.threadId ? { threadId: resolved.threadId } : {},
+							nodes: [{
+								id: root.id,
+								name: root.name,
+								kind: scopeKindLabel(root.address, root.kind),
+								...root.description ? { description: root.description } : {},
+								scope: null,
+								rung: null,
+								isScope: true,
+								pinned: false,
+								recordCount: 0,
+								...scopeCountsById.get(root.id),
+								...rootRow ? {
+									createdAt: rootRow.createdAt.toISOString(),
+									updatedAt: rootRow.updatedAt.toISOString()
+								} : {}
+							}, ...members.map((node) => {
+								const nodeScope = Array.isArray(node.scope) ? node.scope : null;
+								const address = node.isScope ? scopeAddressById.get(node.id) : void 0;
+								return {
+									id: node.id,
+									name: memberSessionNames.get(node.id) ?? node.name,
+									kind: node.isScope ? scopeKindLabel(address ?? "", node.kind) : node.kind,
+									...node.description ? { description: node.description } : {},
+									scope: nodeScope,
+									rung: nodeScope ? deepestRung(nodeScope) : null,
+									...node.isScope ? {
+										isScope: true,
+										...scopeCountsById.get(node.id)
+									} : {},
+									pinned: false,
+									recordCount: recordCounts.get(node.id) ?? 0,
+									createdAt: node.createdAt.toISOString(),
+									updatedAt: node.updatedAt.toISOString()
+								};
+							})],
+							edges,
+							records: graphRecords,
+							truncated,
+							outOfWindow: [...resolver.outOfWindow.values()],
+							unresolvedCapped: {
+								count: resolver.cappedCount,
+								names: resolver.cappedNames
+							},
+							pinCensus: {
+								resource: 0,
+								thread: null
+							},
+							version: activity[0]?.id ?? null
+						};
+						return c.json(payload);
+					}
+					const view = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
+					if (!view) return c.json({ error: "scope_not_found" }, 404);
 					const { store, scope } = view;
 					const limits = this.#limits;
-					const fetched = await store.listNodes({
+					const fetched = (await store.listNodes({
 						scope,
 						limit: limits.maxNodes + 1
-					});
+					})).filter((node) => Array.isArray(node.scope));
 					let truncated = fetched.length > limits.maxNodes;
 					const pinnedNodeIds = await this.#pinnedNodeIds(view);
 					const pinnedNodeIdSet = new Set(pinnedNodeIds.map((p) => p.id));
@@ -358,13 +945,15 @@ var KnowledgeRoutes = class extends Route {
 				method: "GET",
 				requiresAuth: false,
 				handler: async (c) => {
-					const view = await this.#resolveView(loose(c));
-					if ("response" in view) return view.response;
-					const { store, scope } = view;
+					const resolved = await this.#resolveView(loose(c));
+					if ("response" in resolved) return resolved.response;
 					const nodeId = loose(c).req.param("nodeId");
 					if (!nodeId || nodeId.length > 512) return c.json({ error: "node_not_found" }, 404);
+					const view = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
+					if (!view) return c.json({ error: "scope_not_found" }, 404);
+					const { store, scope } = view;
 					const node = await store.getNode(nodeId);
-					if (!node || !isKnowledgeScopeVisible(node.scope, scope)) return c.json({ error: "node_not_found" }, 404);
+					if (!node?.scope || !isKnowledgeScopeVisible(node.scope, scope)) return c.json({ error: "node_not_found" }, 404);
 					const pinnedNodeIds = await this.#pinnedNodeIds(view);
 					const pinnedNodeIdSet = new Set(pinnedNodeIds.map((p) => p.id));
 					const [owned, mentioning] = await Promise.all([store.listKnowledgeAbout({
@@ -403,6 +992,7 @@ var KnowledgeRoutes = class extends Route {
 							name: node.name,
 							kind: node.kind,
 							content: node.content ?? "",
+							...node.description ? { description: node.description } : {},
 							scope: node.scope,
 							rung: deepestRung(node.scope),
 							createdAt: node.createdAt.toISOString(),
@@ -417,25 +1007,120 @@ var KnowledgeRoutes = class extends Route {
 				method: "GET",
 				requiresAuth: false,
 				handler: async (c) => {
-					const view = await this.#resolveView(loose(c));
-					if ("response" in view) return view.response;
-					const events = await view.store.listActivity({
-						scope: view.scope,
-						limit: 100
-					});
-					return c.json({ events: events.map((event) => ({
-						id: event.id,
-						action: event.action,
-						recordType: event.recordType,
-						recordId: event.recordId,
-						scope: event.scope,
-						...event.sourceThreadId ? { sourceThreadId: event.sourceThreadId } : {},
-						createdAt: event.createdAt.toISOString()
-					})) });
+					const resolved = await this.#resolveView(loose(c));
+					if ("response" in resolved) return resolved.response;
+					const scopeNodeId = loose(c).req.query("scopeNodeId");
+					let view;
+					let memberIds;
+					let membersTruncated = false;
+					if (scopeNodeId !== void 0) {
+						if (!UUID_RE.test(scopeNodeId)) return c.json({ error: "scope_not_found" }, 404);
+						let scopeNode;
+						try {
+							scopeNode = await findOrgScopeNode(resolved.store, resolved.orgId, scopeNodeId);
+						} catch (error) {
+							if (error instanceof KnowledgeUnsupportedCapabilityError) return c.json({ error: "scope_not_found" }, 404);
+							throw error;
+						}
+						if (!scopeNode) return c.json({ error: "scope_not_found" }, 404);
+						const { members, hasMore } = await resolved.store.listScopeMembers({
+							scopeNodeId,
+							limit: this.#limits.maxNodes
+						});
+						membersTruncated = hasMore || members.length > this.#limits.maxNodes;
+						memberIds = new Set(members.slice(0, this.#limits.maxNodes).filter((member) => !member.isScope).map((member) => member.id));
+						view = resolved;
+					} else {
+						const selected = this.#selectedView(resolved, loose(c).req.query("scopeLevel"));
+						if (!selected) return c.json({ error: "scope_not_found" }, 404);
+						view = selected;
+					}
+					const cursor = loose(c).req.query("cursor");
+					if (cursor && cursor.length > 128) return c.json({ error: "invalid_activity_cursor" }, 400);
+					const { items: activity, scanCursor } = await this.#visibleActivity(view, memberIds, cursor, 26);
+					const visiblePage = activity.slice(0, ACTIVITY_PAGE_SIZE);
+					const lastVisible = visiblePage.at(-1);
+					const payload = {
+						events: visiblePage.map(({ event, node }) => {
+							const rung = deepestRung(node.scope);
+							const threadId = rung === "thread" ? node.scope.find((address) => address.startsWith("thread:"))?.slice(7) : void 0;
+							return {
+								id: event.id,
+								action: event.action,
+								recordType: event.recordType,
+								...event.recordType === "record" ? { recordId: event.recordId } : {},
+								scope: event.scope,
+								node: {
+									id: node.id,
+									name: node.name,
+									rung,
+									...threadId ? { threadId } : {}
+								},
+								createdAt: event.createdAt.toISOString()
+							};
+						}),
+						...activity.length > ACTIVITY_PAGE_SIZE && lastVisible ? { nextCursor: lastVisible.event.id } : scanCursor ? { nextCursor: scanCursor } : {},
+						...membersTruncated ? { truncated: true } : {}
+					};
+					return c.json(payload);
 				}
 			})
 		];
 	}
+	/**
+	* Newest-first activity page where EVERY returned event targets a node
+	* visible in the view. Visibility is decided BEFORE window shaping: hidden
+	* rows are skipped entirely (no action/type/id/time metadata leaks) and a
+	* hidden backlog can never displace visible events from the window.
+	* When the scan cap stops the walk before the stream ends, `scanCursor` is
+	* the last scanned event so the caller can continue past hidden rows.
+	*/
+	async #visibleActivity(view, memberIds, cursor, limit) {
+		const out = [];
+		const nodes = /* @__PURE__ */ new Map();
+		const getNode = (id) => {
+			let node = nodes.get(id);
+			if (!node) {
+				node = view.store.getNode(id);
+				nodes.set(id, node);
+			}
+			return node;
+		};
+		let after = cursor;
+		let scanned = 0;
+		let exhausted = false;
+		while (out.length < limit && scanned < ACTIVITY_SCAN_CAP) {
+			const batch = await view.store.listActivity({
+				scope: view.scope,
+				after,
+				limit: ACTIVITY_BATCH
+			});
+			if (batch.length === 0) {
+				exhausted = true;
+				break;
+			}
+			for (const event of batch) {
+				after = event.id;
+				scanned += 1;
+				let targetNode;
+				if (event.recordType === "node") targetNode = await getNode(event.recordId);
+				else {
+					const record = await view.store.getKnowledge({ id: event.recordId });
+					targetNode = record ? await getNode(record.node) : null;
+					if (record && !isKnowledgeScopeVisible(record.scope, view.scope)) targetNode = null;
+				}
+				if (targetNode?.scope && isKnowledgeScopeVisible(targetNode.scope, view.scope) && (memberIds === void 0 || memberIds.has(targetNode.id))) out.push({
+					event,
+					node: targetNode
+				});
+				if (out.length >= limit || scanned >= ACTIVITY_SCAN_CAP) break;
+			}
+		}
+		return {
+			items: out,
+			...!exhausted && out.length < limit && scanned >= ACTIVITY_SCAN_CAP && after ? { scanCursor: after } : {}
+		};
+	}
 };
 //#endregion
 export { KnowledgeRoutes };