@mastra/code-sdk 0.0.0-aggregate-trace-20261015182851

package/dist/knowledge-inspector.js

@@ -0,0 +1,516 @@
+import { resolveKnowledgeScopeIdentity } from "./knowledge-scope.js";
+import { createKnowledgeNodeCursor, isKnowledgeScopeVisible, parseKnowledgeWikilinks } from "@mastra/core/storage";
+//#region src/knowledge-inspector.ts
+var KnowledgeInspectorError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "KnowledgeInspectorError";
+	}
+};
+const HANDLE_TTL_MS = 5 * 6e4;
+const MAX_OPAQUE_ENTRIES = 1e3;
+const DEFAULT_RECORD_LIMIT = 50;
+const MAX_RECORD_LIMIT = 50;
+const DEFAULT_FACT_LIMIT = 25;
+const MAX_FACT_LIMIT = 100;
+const DEFAULT_ACTIVITY_LIMIT = 20;
+const MAX_ACTIVITY_LIMIT = 100;
+const MAX_RELATED_RECORDS = 25;
+const MAX_RANK_CANDIDATES = 50;
+const MAX_RANK_FACTS = 100;
+const RRF_K = 60;
+const MAX_NODE_CONTENT_BYTES = 32 * 1024;
+function opaqueToken() {
+	return Buffer.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(24))).toString("base64url");
+}
+function boundedLimit(value, fallback, maximum) {
+	if (value === void 0) return fallback;
+	if (!Number.isInteger(value) || value < 1) return fallback;
+	return Math.min(value, maximum);
+}
+function scopeBadge(scope) {
+	const entry = scope.at(-1);
+	if (!entry) throw new KnowledgeInspectorError("unavailable", "Knowledge record has no scope.");
+	const separator = entry.indexOf(":");
+	return {
+		level: entry.slice(0, separator),
+		id: entry.slice(separator + 1)
+	};
+}
+function knowledgeSummary(record) {
+	return {
+		text: record.text,
+		scope: scopeBadge(record.scope),
+		sourceThreadId: record.sourceThreadId,
+		capturedAt: record.capturedAt.toISOString(),
+		when: record.when?.toISOString()
+	};
+}
+function truncateUtf8(value, maxBytes) {
+	const encoded = Buffer.from(value);
+	if (encoded.byteLength <= maxBytes) return {
+		value,
+		truncated: false
+	};
+	let end = maxBytes;
+	let truncated = encoded.subarray(0, end).toString("utf8");
+	while (Buffer.byteLength(truncated) > maxBytes) truncated = encoded.subarray(0, --end).toString("utf8");
+	return {
+		value: truncated,
+		truncated: true
+	};
+}
+var ScopedKnowledgeInspector = class {
+	#knowledge;
+	#session;
+	#handles = /* @__PURE__ */ new Map();
+	#cursors = /* @__PURE__ */ new Map();
+	#fingerprint;
+	#identityKey = opaqueToken();
+	constructor(input) {
+		this.#knowledge = input.knowledge;
+		this.#session = input.session;
+		this.#session.subscribe((event) => {
+			if (event.type === "thread_changed" || event.type === "thread_created" || event.type === "thread_deleted") this.#invalidateIdnode();
+		});
+	}
+	async getScopeTree() {
+		const binding = await this.#binding();
+		return {
+			identityKey: binding.identityKey,
+			defaultLevel: "resource",
+			roots: [
+				{
+					level: "org",
+					id: binding.organizationId,
+					available: true
+				},
+				{
+					level: "resource",
+					id: binding.resourceId,
+					available: true
+				},
+				binding.threadId ? {
+					level: "thread",
+					id: binding.threadId,
+					available: true
+				} : {
+					level: "thread",
+					available: false,
+					reason: "No active thread belongs to this project."
+				}
+			]
+		};
+	}
+	async listNodes(input) {
+		const binding = await this.#binding();
+		const scope = this.#scope(binding, input.level);
+		const limit = boundedLimit(input.limit, DEFAULT_RECORD_LIMIT, MAX_RECORD_LIMIT);
+		const sort = input.sort ?? "relevant";
+		if (sort === "recent") {
+			const cursor = this.#consumeCursor(input.cursor, binding, input.level, "node", {
+				namePrefix: input.namePrefix,
+				kind: input.kind,
+				sort
+			});
+			const records = await this.#knowledge.listNodes({
+				scope,
+				namePrefix: input.namePrefix,
+				kind: input.kind,
+				cursor,
+				limit
+			});
+			const nodes = await Promise.all(records.map(async (record) => ({
+				...this.#recordSummary(record, binding, input.level),
+				relationshipCounts: (await this.#sampledRelationshipCounts(record, scope)).counts
+			})));
+			await this.#assertStable(binding);
+			return {
+				identityKey: binding.identityKey,
+				scopeLevel: input.level,
+				nodes,
+				nextCursor: records.length === limit ? this.#mintCursor(binding, input.level, "node", createKnowledgeNodeCursor(records.at(-1), {
+					namePrefix: input.namePrefix,
+					kind: input.kind
+				}), {
+					namePrefix: input.namePrefix,
+					kind: input.kind,
+					sort
+				}) : void 0,
+				sort,
+				coverage: "exact"
+			};
+		}
+		const filters = {
+			namePrefix: input.namePrefix,
+			kind: input.kind,
+			sort
+		};
+		const encodedSnapshot = this.#consumeCursor(input.cursor, binding, input.level, "ranked-node", filters);
+		const snapshot = encodedSnapshot ? JSON.parse(encodedSnapshot) : await this.#rankedNodeSnapshot(scope, input.namePrefix, input.kind, sort);
+		const page = snapshot.entries.slice(snapshot.offset, snapshot.offset + limit);
+		const nodes = [];
+		for (const entry of page) {
+			const node = await this.#knowledge.getNode(entry.id);
+			if (!node || !isKnowledgeScopeVisible(node.scope, scope)) continue;
+			nodes.push({
+				...this.#recordSummary(node, binding, input.level),
+				relationshipCounts: entry.counts
+			});
+		}
+		const nextOffset = snapshot.offset + limit;
+		await this.#assertStable(binding);
+		return {
+			identityKey: binding.identityKey,
+			scopeLevel: input.level,
+			nodes,
+			nextCursor: nextOffset < snapshot.entries.length ? this.#mintCursor(binding, input.level, "ranked-node", JSON.stringify({
+				...snapshot,
+				offset: nextOffset
+			}), filters) : void 0,
+			sort,
+			coverage: "recent-window"
+		};
+	}
+	async getNode(input) {
+		const binding = await this.#binding();
+		const handle = this.#readHandle(input.handle, binding, "node");
+		const scope = this.#scope(binding, handle.level);
+		const node = await this.#knowledge.getNode(handle.recordId);
+		this.#assertVisible(node, scope);
+		const limit = boundedLimit(input.recordLimit, DEFAULT_FACT_LIMIT, MAX_FACT_LIMIT);
+		const recordsAfter = this.#consumeCursor(input.recordsCursor, binding, handle.level, "records");
+		const mentioningAfter = this.#consumeCursor(input.mentioningRecordsCursor, binding, handle.level, "mentioning-records");
+		const [recordsResult, mentioningResult] = await Promise.all([this.#knowledge.listKnowledgeAbout({
+			node: node.id,
+			scope,
+			after: recordsAfter,
+			limit
+		}), this.#knowledge.listKnowledgeMentioning({
+			node: node.id,
+			scope,
+			after: mentioningAfter,
+			limit
+		})]);
+		const mentioningRecords = mentioningResult.records.filter((record) => record.node !== node.id);
+		const content = truncateUtf8(node.content ?? "", MAX_NODE_CONTENT_BYTES);
+		const [outgoingTargets, incomingParents, relationship] = await Promise.all([
+			this.#outgoingTargets(node, recordsResult.records, scope, binding, handle.level),
+			this.#incomingParents(node, mentioningRecords, scope, binding, handle.level),
+			this.#sampledRelationshipCounts(node, scope)
+		]);
+		const links = await Promise.all(parseKnowledgeWikilinks(content.value).slice(0, MAX_RELATED_RECORDS).map(async (label) => {
+			const target = await this.#knowledge.resolveNode({
+				name: label,
+				scope
+			});
+			return {
+				label,
+				node: target ? this.#recordSummary(target, binding, handle.level) : void 0
+			};
+		}));
+		await this.#assertStable(binding);
+		return {
+			identityKey: binding.identityKey,
+			scopeLevel: handle.level,
+			node: {
+				...this.#recordSummary(node, binding, handle.level),
+				relationshipCounts: relationship.counts
+			},
+			records: recordsResult.records.map(knowledgeSummary),
+			recordsNextCursor: recordsResult.nextCursor ? this.#mintCursor(binding, handle.level, "records", recordsResult.nextCursor) : void 0,
+			mentioningRecords: mentioningRecords.map(knowledgeSummary),
+			mentioningRecordsNextCursor: mentioningResult.nextCursor ? this.#mintCursor(binding, handle.level, "mentioning-records", mentioningResult.nextCursor) : void 0,
+			outgoingTargets: {
+				nodes: outgoingTargets.nodes,
+				partial: outgoingTargets.partial || Boolean(recordsResult.nextCursor)
+			},
+			incomingParents: {
+				nodes: incomingParents.nodes,
+				partial: incomingParents.partial || Boolean(mentioningResult.nextCursor)
+			},
+			relationshipCounts: relationship.counts,
+			content: node.content === void 0 ? void 0 : content.value,
+			contentTruncated: content.truncated,
+			links
+		};
+	}
+	async listActivity(input) {
+		const binding = await this.#binding();
+		const scope = this.#scope(binding, input.level);
+		const limit = boundedLimit(input.limit, DEFAULT_ACTIVITY_LIMIT, MAX_ACTIVITY_LIMIT);
+		const after = this.#consumeCursor(input.cursor, binding, input.level, "activity");
+		const events = await this.#knowledge.listActivity({
+			scope,
+			after,
+			limit
+		});
+		const activityEvents = [];
+		for (const event of events) {
+			const record = await this.#activityRecord(event, scope, binding, input.level);
+			activityEvents.push({
+				action: event.action,
+				recordType: event.recordType,
+				scope: scopeBadge(event.scope),
+				sourceThreadId: record ? event.sourceThreadId : void 0,
+				createdAt: event.createdAt.toISOString(),
+				record
+			});
+		}
+		await this.#assertStable(binding);
+		return {
+			identityKey: binding.identityKey,
+			scopeLevel: input.level,
+			events: activityEvents,
+			nextCursor: events.length === limit ? this.#mintCursor(binding, input.level, "activity", events.at(-1).id) : void 0
+		};
+	}
+	async #binding() {
+		const identity = resolveKnowledgeScopeIdentity(this.#session.state.get());
+		const sessionResourceId = this.#session.identity.getResourceId();
+		if (!identity.resolved) {
+			this.#invalidateIdnode();
+			throw new KnowledgeInspectorError("unavailable", identity.reason ? `Knowledge inspection unavailable: ${identity.reason}` : "Knowledge inspection requires a resolved organization for this session.");
+		}
+		if (!sessionResourceId) throw new KnowledgeInspectorError("unavailable", "Knowledge inspection requires an active project.");
+		const organizationId = identity.organizationId;
+		const resourceId = identity.knowledgeResourceId ?? sessionResourceId;
+		const activeThreadId = this.#session.thread.getId() ?? void 0;
+		const thread = activeThreadId ? await this.#session.thread.getById({ threadId: activeThreadId }) : null;
+		const threadId = thread?.resourceId === sessionResourceId ? thread.id : void 0;
+		const fingerprint = `${organizationId}\0${resourceId}\0${threadId ?? ""}`;
+		if (this.#fingerprint !== fingerprint) {
+			this.#fingerprint = fingerprint;
+			this.#identityKey = opaqueToken();
+			this.#handles.clear();
+			this.#cursors.clear();
+		}
+		return {
+			organizationId,
+			resourceId,
+			threadId,
+			fingerprint,
+			identityKey: this.#identityKey
+		};
+	}
+	#scope(binding, level) {
+		if (level === "org") return [`org:${binding.organizationId}`];
+		const scope = [`org:${binding.organizationId}`, `resource:${binding.resourceId}`];
+		if (level === "resource") return scope;
+		if (!binding.threadId) throw new KnowledgeInspectorError("unavailable", "The active thread does not belong to this project.");
+		return [...scope, `thread:${binding.threadId}`];
+	}
+	async #assertStable(binding) {
+		const current = await this.#binding();
+		if (current.identityKey !== binding.identityKey || current.fingerprint !== binding.fingerprint) throw new KnowledgeInspectorError("stale-handle", "Knowledge scope changed while the request was running.");
+	}
+	#assertVisible(record, scope) {
+		if (!record || !isKnowledgeScopeVisible(record.scope, scope)) throw new KnowledgeInspectorError("not-visible", "Knowledge record is not visible in the selected scope.");
+	}
+	#recordSummary(record, binding, level) {
+		const type = "node";
+		return {
+			handle: this.#mintHandle(binding, level, type, record.id),
+			type,
+			name: record.name,
+			kind: record.kind,
+			scope: scopeBadge(record.scope),
+			version: record.version,
+			updatedAt: record.updatedAt.toISOString()
+		};
+	}
+	async #rankedNodeSnapshot(scope, namePrefix, kind, sort) {
+		const records = await this.#knowledge.listNodes({
+			scope,
+			namePrefix,
+			kind,
+			limit: MAX_RANK_CANDIDATES
+		});
+		const ranked = await Promise.all(records.map(async (node, recencyRank) => ({
+			node,
+			recencyRank,
+			...await this.#sampledRelationshipCounts(node, scope)
+		})));
+		const connected = [...ranked].sort((a, b) => b.degree - a.degree || a.recencyRank - b.recencyRank || a.node.id.localeCompare(b.node.id));
+		const connectedRank = new Map(connected.map((entry, index) => [entry.node.id, index]));
+		return {
+			offset: 0,
+			entries: (sort === "connected" ? connected : [...ranked].sort((a, b) => {
+				const aScore = 1 / (RRF_K + a.recencyRank + 1) + 1 / (RRF_K + connectedRank.get(a.node.id) + 1);
+				return 1 / (RRF_K + b.recencyRank + 1) + 1 / (RRF_K + connectedRank.get(b.node.id) + 1) - aScore || a.recencyRank - b.recencyRank || a.node.id.localeCompare(b.node.id);
+			})).map((entry) => ({
+				id: entry.node.id,
+				degree: entry.degree,
+				counts: entry.counts
+			}))
+		};
+	}
+	async #sampledRelationshipCounts(node, scope) {
+		const [aboutResult, mentioningResult] = await Promise.all([this.#knowledge.listKnowledgeAbout({
+			node: node.id,
+			scope,
+			limit: MAX_RANK_FACTS
+		}), this.#knowledge.listKnowledgeMentioning({
+			node: node.id,
+			scope,
+			limit: MAX_RANK_FACTS
+		})]);
+		const [outgoing, incoming] = await Promise.all([this.#outgoingNodeRecords(node, aboutResult.records, scope), this.#incomingParentRecords(node, mentioningResult.records, scope)]);
+		const mentioningRecords = mentioningResult.records.filter((record) => record.node !== node.id);
+		return {
+			degree: new Set([...outgoing.nodes, ...incoming.nodes].map((record) => record.id)).size,
+			counts: {
+				records: aboutResult.records.length + mentioningRecords.length,
+				outgoing: outgoing.nodes.length,
+				incoming: incoming.nodes.length,
+				sampled: Boolean(aboutResult.nextCursor || mentioningResult.nextCursor || outgoing.truncated || incoming.truncated)
+			}
+		};
+	}
+	async #outgoingNodeRecords(current, records, scope) {
+		const related = /* @__PURE__ */ new Map();
+		let truncated = false;
+		const sources = [current.content ?? "", ...records.map((record) => record.text)];
+		for (const source of sources) {
+			for (const name of parseKnowledgeWikilinks(source)) {
+				if (related.size >= MAX_RELATED_RECORDS) {
+					truncated = true;
+					break;
+				}
+				const node = await this.#knowledge.resolveNode({
+					name,
+					scope
+				});
+				if (node && node.id !== current.id && isKnowledgeScopeVisible(node.scope, scope)) related.set(node.id, node);
+			}
+			if (truncated) break;
+		}
+		return {
+			nodes: [...related.values()],
+			truncated
+		};
+	}
+	async #incomingParentRecords(current, records, scope) {
+		const related = /* @__PURE__ */ new Map();
+		let truncated = false;
+		for (const record of records) {
+			if (record.node === current.id || related.has(record.node)) continue;
+			if (related.size >= MAX_RELATED_RECORDS) {
+				truncated = true;
+				break;
+			}
+			const node = await this.#knowledge.getNode(record.node);
+			if (node && isKnowledgeScopeVisible(node.scope, scope)) related.set(node.id, node);
+		}
+		return {
+			nodes: [...related.values()],
+			truncated
+		};
+	}
+	async #outgoingTargets(current, records, scope, binding, level) {
+		const related = await this.#outgoingNodeRecords(current, records, scope);
+		return {
+			nodes: related.nodes.map((node) => this.#recordSummary(node, binding, level)),
+			partial: related.truncated
+		};
+	}
+	async #incomingParents(current, records, scope, binding, level) {
+		const related = await this.#incomingParentRecords(current, records, scope);
+		return {
+			nodes: related.nodes.map((node) => this.#recordSummary(node, binding, level)),
+			partial: related.truncated
+		};
+	}
+	async #activityRecord(event, scope, binding, level) {
+		if (event.recordType === "node") {
+			const node = await this.#knowledge.getNode(event.recordId);
+			return node && isKnowledgeScopeVisible(node.scope, scope) ? this.#recordSummary(node, binding, level) : void 0;
+		}
+		const record = await this.#knowledge.getKnowledge({
+			id: event.recordId,
+			includeDeleted: true
+		});
+		if (!record || !isKnowledgeScopeVisible(record.scope, scope)) return void 0;
+		const node = await this.#knowledge.getNode(record.node);
+		return node && isKnowledgeScopeVisible(node.scope, scope) ? this.#recordSummary(node, binding, level) : void 0;
+	}
+	#mintHandle(binding, level, type, recordId) {
+		this.#pruneOpaqueEntries();
+		const token = opaqueToken();
+		this.#handles.set(token, {
+			identityKey: binding.identityKey,
+			level,
+			type,
+			recordId,
+			expiresAt: Date.now() + HANDLE_TTL_MS
+		});
+		return token;
+	}
+	#readHandle(handle, binding, expectedType) {
+		const entry = this.#handles.get(handle);
+		if (!entry || entry.expiresAt < Date.now() || entry.type !== expectedType) throw new KnowledgeInspectorError("invalid-handle", "Knowledge record handle is invalid or expired.");
+		if (entry.identityKey !== binding.identityKey) throw new KnowledgeInspectorError("stale-handle", "Knowledge record handle belongs to a previous scope.");
+		return entry;
+	}
+	#mintCursor(binding, level, kind, value, filters) {
+		this.#pruneOpaqueEntries();
+		const token = opaqueToken();
+		this.#cursors.set(token, {
+			identityKey: binding.identityKey,
+			level,
+			kind,
+			value,
+			filters,
+			expiresAt: Date.now() + HANDLE_TTL_MS
+		});
+		return token;
+	}
+	#consumeCursor(cursor, binding, level, kind, filters) {
+		if (!cursor) return void 0;
+		const entry = this.#cursors.get(cursor);
+		if (!entry || entry.expiresAt < Date.now() || entry.identityKey !== binding.identityKey || entry.level !== level || entry.kind !== kind || entry.filters?.namePrefix !== filters?.namePrefix || entry.filters?.kind !== filters?.kind || entry.filters?.sort !== filters?.sort) throw new KnowledgeInspectorError("invalid-cursor", "Knowledge cursor does not match the active scope and filters.");
+		return entry.value;
+	}
+	#pruneOpaqueEntries() {
+		const now = Date.now();
+		for (const [token, entry] of this.#handles) if (entry.expiresAt < now) this.#handles.delete(token);
+		for (const [token, entry] of this.#cursors) if (entry.expiresAt < now) this.#cursors.delete(token);
+		while (this.#handles.size + this.#cursors.size >= MAX_OPAQUE_ENTRIES) {
+			const handle = this.#handles.keys().next().value;
+			if (handle) this.#handles.delete(handle);
+			else {
+				const cursor = this.#cursors.keys().next().value;
+				if (cursor) this.#cursors.delete(cursor);
+				else break;
+			}
+		}
+	}
+	#invalidateIdnode() {
+		this.#fingerprint = void 0;
+		this.#identityKey = opaqueToken();
+		this.#handles.clear();
+		this.#cursors.clear();
+	}
+};
+async function createKnowledgeInspector(input) {
+	let selected;
+	if (typeof input.knowledge === "string") {
+		try {
+			selected = input.mastra?.getKnowledge(input.knowledge);
+		} catch {
+			throw new KnowledgeInspectorError("unavailable", "The configured Knowledge runtime is unavailable.");
+		}
+		if (!selected) throw new KnowledgeInspectorError("unavailable", "The configured Knowledge runtime is unavailable.");
+	} else selected = input.knowledge;
+	const knowledge = selected ? await selected.getStorage() : await input.storage.getStore("knowledge");
+	return knowledge ? new ScopedKnowledgeInspector({
+		knowledge,
+		session: input.session
+	}) : void 0;
+}
+//#endregion
+export { KnowledgeInspectorError, createKnowledgeInspector };
+
+//# sourceMappingURL=knowledge-inspector.js.map

package/dist/knowledge-inspector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-inspector.js","names":["#knowledge","#session","#handles","#cursors","#invalidateIdnode","#binding","#scope","#consumeCursor","#recordSummary","#sampledRelationshipCounts","#assertStable","#mintCursor","#rankedNodeSnapshot","#readHandle","#assertVisible","#outgoingTargets","#incomingParents","#activityRecord","#fingerprint","#identityKey","#mintHandle","#outgoingNodeRecords","#incomingParentRecords","#pruneOpaqueEntries"],"sources":["../src/knowledge-inspector.ts"],"sourcesContent":["import type { Session } from '@mastra/core/agent-controller';\nimport type { Knowledge } from '@mastra/core/knowledge';\nimport type { Mastra } from '@mastra/core/mastra';\nimport { createKnowledgeNodeCursor, isKnowledgeScopeVisible, parseKnowledgeWikilinks } from '@mastra/core/storage';\nimport type {\n  KnowledgeActivityEvent,\n  KnowledgeRecord,\n  KnowledgeNode,\n  KnowledgeScope,\n  KnowledgeStorage,\n  MastraCompositeStore,\n} from '@mastra/core/storage';\n\nimport { resolveKnowledgeScopeIdentity } from './knowledge-scope.js';\nimport type { MastraCodeState } from './schema.js';\n\nexport type KnowledgeInspectorScopeLevel = 'org' | 'resource' | 'thread';\nexport type KnowledgeInspectorRecordType = 'node';\nexport type KnowledgeInspectorNodeSort = 'relevant' | 'recent' | 'connected';\n\nexport interface KnowledgeInspectorScopeRoot {\n  level: KnowledgeInspectorScopeLevel;\n  id?: string;\n  available: boolean;\n  reason?: string;\n}\n\nexport interface KnowledgeInspectorScopeTree {\n  identityKey: string;\n  defaultLevel: 'resource';\n  roots: KnowledgeInspectorScopeRoot[];\n}\n\nexport interface KnowledgeInspectorScopeBadge {\n  level: KnowledgeInspectorScopeLevel;\n  id: string;\n}\n\nexport interface KnowledgeInspectorRelationshipCounts {\n  records: number;\n  outgoing: number;\n  incoming: number;\n  sampled: boolean;\n}\n\nexport interface KnowledgeInspectorNodeSummary {\n  handle: string;\n  type: KnowledgeInspectorRecordType;\n  name: string;\n  kind?: string;\n  scope: KnowledgeInspectorScopeBadge;\n  version: number;\n  updatedAt: string;\n  relationshipCounts?: KnowledgeInspectorRelationshipCounts;\n}\n\nexport interface KnowledgeInspectorRecordSummary {\n  text: string;\n  scope: KnowledgeInspectorScopeBadge;\n  sourceThreadId: string;\n  capturedAt: string;\n  when?: string;\n}\n\nexport interface KnowledgeInspectorNodeList {\n  identityKey: string;\n  scopeLevel: KnowledgeInspectorScopeLevel;\n  nodes: KnowledgeInspectorNodeSummary[];\n  nextCursor?: string;\n  sort?: KnowledgeInspectorNodeSort;\n  coverage?: 'exact' | 'recent-window';\n}\n\nexport interface KnowledgeInspectorRelationshipPreview {\n  nodes: KnowledgeInspectorNodeSummary[];\n  partial: boolean;\n}\n\nexport interface KnowledgeInspectorNodeDetail {\n  identityKey: string;\n  scopeLevel: KnowledgeInspectorScopeLevel;\n  node: KnowledgeInspectorNodeSummary;\n  records: KnowledgeInspectorRecordSummary[];\n  recordsNextCursor?: string;\n  mentioningRecords: KnowledgeInspectorRecordSummary[];\n  mentioningRecordsNextCursor?: string;\n  outgoingTargets: KnowledgeInspectorRelationshipPreview;\n  incomingParents: KnowledgeInspectorRelationshipPreview;\n  relationshipCounts: KnowledgeInspectorRelationshipCounts;\n  content?: string;\n  contentTruncated: boolean;\n  links: Array<{ label: string; node?: KnowledgeInspectorNodeSummary }>;\n}\n\nexport interface KnowledgeInspectorActivityEvent {\n  action: KnowledgeActivityEvent['action'];\n  recordType: KnowledgeActivityEvent['recordType'];\n  scope: KnowledgeInspectorScopeBadge;\n  sourceThreadId?: string;\n  createdAt: string;\n  record?: KnowledgeInspectorNodeSummary;\n}\n\nexport interface KnowledgeInspectorActivityList {\n  identityKey: string;\n  scopeLevel: KnowledgeInspectorScopeLevel;\n  events: KnowledgeInspectorActivityEvent[];\n  nextCursor?: string;\n}\n\nexport interface KnowledgeInspector {\n  getScopeTree(): Promise<KnowledgeInspectorScopeTree>;\n  listNodes(input: {\n    level: KnowledgeInspectorScopeLevel;\n    namePrefix?: string;\n    kind?: string;\n    sort?: KnowledgeInspectorNodeSort;\n    cursor?: string;\n    limit?: number;\n  }): Promise<KnowledgeInspectorNodeList>;\n  getNode(input: {\n    handle: string;\n    recordsCursor?: string;\n    mentioningRecordsCursor?: string;\n    recordLimit?: number;\n  }): Promise<KnowledgeInspectorNodeDetail>;\n  listActivity(input: {\n    level: KnowledgeInspectorScopeLevel;\n    cursor?: string;\n    limit?: number;\n  }): Promise<KnowledgeInspectorActivityList>;\n}\n\nexport class KnowledgeInspectorError extends Error {\n  constructor(\n    readonly code: 'unavailable' | 'invalid-handle' | 'stale-handle' | 'invalid-cursor' | 'not-visible',\n    message: string,\n  ) {\n    super(message);\n    this.name = 'KnowledgeInspectorError';\n  }\n}\n\ninterface Binding {\n  /** Org rung shared with the subconscious writers (see knowledge-scope.ts). */\n  organizationId: string;\n  /** Resource rung of the knowledge scope: the Factory project id, else the session resource. */\n  resourceId: string;\n  threadId?: string;\n  fingerprint: string;\n  identityKey: string;\n}\n\ninterface HandleEntry {\n  identityKey: string;\n  level: KnowledgeInspectorScopeLevel;\n  type: KnowledgeInspectorRecordType;\n  recordId: string;\n  expiresAt: number;\n}\n\ninterface CursorEntry {\n  identityKey: string;\n  level: KnowledgeInspectorScopeLevel;\n  kind: 'node' | 'ranked-node' | 'records' | 'mentioning-records' | 'activity';\n  value: string;\n  filters?: { namePrefix?: string; kind?: string; sort?: KnowledgeInspectorNodeSort };\n  expiresAt: number;\n}\n\ninterface RankedNodeSnapshot {\n  offset: number;\n  entries: { id: string; degree: number; counts: KnowledgeInspectorRelationshipCounts }[];\n}\n\ninterface RelationshipRecords {\n  nodes: KnowledgeNode[];\n  truncated: boolean;\n}\n\nconst HANDLE_TTL_MS = 5 * 60_000;\nconst MAX_OPAQUE_ENTRIES = 1_000;\nconst DEFAULT_RECORD_LIMIT = 50;\nconst MAX_RECORD_LIMIT = 50;\nconst DEFAULT_FACT_LIMIT = 25;\nconst MAX_FACT_LIMIT = 100;\nconst DEFAULT_ACTIVITY_LIMIT = 20;\nconst MAX_ACTIVITY_LIMIT = 100;\nconst MAX_RELATED_RECORDS = 25;\nconst MAX_RANK_CANDIDATES = 50;\nconst MAX_RANK_FACTS = 100;\nconst RRF_K = 60;\nconst MAX_NODE_CONTENT_BYTES = 32 * 1024;\n\nfunction opaqueToken(): string {\n  return Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(24))).toString('base64url');\n}\n\nfunction boundedLimit(value: number | undefined, fallback: number, maximum: number): number {\n  if (value === undefined) return fallback;\n  if (!Number.isInteger(value) || value < 1) return fallback;\n  return Math.min(value, maximum);\n}\n\nfunction scopeBadge(scope: KnowledgeScope): KnowledgeInspectorScopeBadge {\n  const entry = scope.at(-1);\n  if (!entry) throw new KnowledgeInspectorError('unavailable', 'Knowledge record has no scope.');\n  const separator = entry.indexOf(':');\n  return {\n    level: entry.slice(0, separator) as KnowledgeInspectorScopeLevel,\n    id: entry.slice(separator + 1),\n  };\n}\n\nfunction knowledgeSummary(record: KnowledgeRecord): KnowledgeInspectorRecordSummary {\n  return {\n    text: record.text,\n    scope: scopeBadge(record.scope),\n    sourceThreadId: record.sourceThreadId,\n    capturedAt: record.capturedAt.toISOString(),\n    when: record.when?.toISOString(),\n  };\n}\n\nfunction truncateUtf8(value: string, maxBytes: number): { value: string; truncated: boolean } {\n  const encoded = Buffer.from(value);\n  if (encoded.byteLength <= maxBytes) return { value, truncated: false };\n  let end = maxBytes;\n  let truncated = encoded.subarray(0, end).toString('utf8');\n  while (Buffer.byteLength(truncated) > maxBytes) {\n    truncated = encoded.subarray(0, --end).toString('utf8');\n  }\n  return { value: truncated, truncated: true };\n}\n\nclass ScopedKnowledgeInspector implements KnowledgeInspector {\n  readonly #knowledge: KnowledgeStorage;\n  readonly #session: Session<MastraCodeState>;\n  readonly #handles = new Map<string, HandleEntry>();\n  readonly #cursors = new Map<string, CursorEntry>();\n  #fingerprint?: string;\n  #identityKey = opaqueToken();\n\n  constructor(input: { knowledge: KnowledgeStorage; session: Session<MastraCodeState> }) {\n    this.#knowledge = input.knowledge;\n    this.#session = input.session;\n    this.#session.subscribe(event => {\n      if (event.type === 'thread_changed' || event.type === 'thread_created' || event.type === 'thread_deleted') {\n        this.#invalidateIdnode();\n      }\n    });\n  }\n\n  async getScopeTree(): Promise<KnowledgeInspectorScopeTree> {\n    const binding = await this.#binding();\n    return {\n      identityKey: binding.identityKey,\n      defaultLevel: 'resource',\n      roots: [\n        { level: 'org', id: binding.organizationId, available: true },\n        { level: 'resource', id: binding.resourceId, available: true },\n        binding.threadId\n          ? { level: 'thread', id: binding.threadId, available: true }\n          : { level: 'thread', available: false, reason: 'No active thread belongs to this project.' },\n      ],\n    };\n  }\n\n  async listNodes(input: {\n    level: KnowledgeInspectorScopeLevel;\n    namePrefix?: string;\n    kind?: string;\n    sort?: KnowledgeInspectorNodeSort;\n    cursor?: string;\n    limit?: number;\n  }): Promise<KnowledgeInspectorNodeList> {\n    const binding = await this.#binding();\n    const scope = this.#scope(binding, input.level);\n    const limit = boundedLimit(input.limit, DEFAULT_RECORD_LIMIT, MAX_RECORD_LIMIT);\n    const sort = input.sort ?? 'relevant';\n    if (sort === 'recent') {\n      const cursor = this.#consumeCursor(input.cursor, binding, input.level, 'node', {\n        namePrefix: input.namePrefix,\n        kind: input.kind,\n        sort,\n      });\n      const records = await this.#knowledge.listNodes({\n        scope,\n        namePrefix: input.namePrefix,\n        kind: input.kind,\n        cursor,\n        limit,\n      });\n      const nodes: KnowledgeInspectorNodeSummary[] = await Promise.all(\n        records.map(async record => ({\n          ...this.#recordSummary(record, binding, input.level),\n          relationshipCounts: (await this.#sampledRelationshipCounts(record, scope)).counts,\n        })),\n      );\n      await this.#assertStable(binding);\n      return {\n        identityKey: binding.identityKey,\n        scopeLevel: input.level,\n        nodes,\n        nextCursor:\n          records.length === limit\n            ? this.#mintCursor(\n                binding,\n                input.level,\n                'node',\n                createKnowledgeNodeCursor(records.at(-1)!, {\n                  namePrefix: input.namePrefix,\n                  kind: input.kind,\n                }),\n                {\n                  namePrefix: input.namePrefix,\n                  kind: input.kind,\n                  sort,\n                },\n              )\n            : undefined,\n        sort,\n        coverage: 'exact',\n      };\n    }\n\n    const filters = { namePrefix: input.namePrefix, kind: input.kind, sort };\n    const encodedSnapshot = this.#consumeCursor(input.cursor, binding, input.level, 'ranked-node', filters);\n    const snapshot = encodedSnapshot\n      ? (JSON.parse(encodedSnapshot) as RankedNodeSnapshot)\n      : await this.#rankedNodeSnapshot(scope, input.namePrefix, input.kind, sort);\n    const page = snapshot.entries.slice(snapshot.offset, snapshot.offset + limit);\n    const nodes: KnowledgeInspectorNodeSummary[] = [];\n    for (const entry of page) {\n      const node = await this.#knowledge.getNode(entry.id);\n      if (!node || !isKnowledgeScopeVisible(node.scope, scope)) continue;\n      nodes.push({ ...this.#recordSummary(node, binding, input.level), relationshipCounts: entry.counts });\n    }\n    const nextOffset = snapshot.offset + limit;\n    await this.#assertStable(binding);\n    return {\n      identityKey: binding.identityKey,\n      scopeLevel: input.level,\n      nodes,\n      nextCursor:\n        nextOffset < snapshot.entries.length\n          ? this.#mintCursor(\n              binding,\n              input.level,\n              'ranked-node',\n              JSON.stringify({ ...snapshot, offset: nextOffset } satisfies RankedNodeSnapshot),\n              filters,\n            )\n          : undefined,\n      sort,\n      coverage: 'recent-window',\n    };\n  }\n\n  async getNode(input: {\n    handle: string;\n    recordsCursor?: string;\n    mentioningRecordsCursor?: string;\n    recordLimit?: number;\n  }): Promise<KnowledgeInspectorNodeDetail> {\n    const binding = await this.#binding();\n    const handle = this.#readHandle(input.handle, binding, 'node');\n    const scope = this.#scope(binding, handle.level);\n    const node = await this.#knowledge.getNode(handle.recordId);\n    this.#assertVisible(node, scope);\n    const limit = boundedLimit(input.recordLimit, DEFAULT_FACT_LIMIT, MAX_FACT_LIMIT);\n    const recordsAfter = this.#consumeCursor(input.recordsCursor, binding, handle.level, 'records');\n    const mentioningAfter = this.#consumeCursor(\n      input.mentioningRecordsCursor,\n      binding,\n      handle.level,\n      'mentioning-records',\n    );\n    const [recordsResult, mentioningResult] = await Promise.all([\n      this.#knowledge.listKnowledgeAbout({ node: node.id, scope, after: recordsAfter, limit }),\n      this.#knowledge.listKnowledgeMentioning({ node: node.id, scope, after: mentioningAfter, limit }),\n    ]);\n    const mentioningRecords = mentioningResult.records.filter(record => record.node !== node.id);\n    const content = truncateUtf8(node.content ?? '', MAX_NODE_CONTENT_BYTES);\n    const [outgoingTargets, incomingParents, relationship] = await Promise.all([\n      this.#outgoingTargets(node, recordsResult.records, scope, binding, handle.level),\n      this.#incomingParents(node, mentioningRecords, scope, binding, handle.level),\n      this.#sampledRelationshipCounts(node, scope),\n    ]);\n    const links = await Promise.all(\n      parseKnowledgeWikilinks(content.value)\n        .slice(0, MAX_RELATED_RECORDS)\n        .map(async label => {\n          const target = await this.#knowledge.resolveNode({ name: label, scope });\n          return {\n            label,\n            node: target ? this.#recordSummary(target, binding, handle.level) : undefined,\n          };\n        }),\n    );\n    await this.#assertStable(binding);\n    return {\n      identityKey: binding.identityKey,\n      scopeLevel: handle.level,\n      node: { ...this.#recordSummary(node, binding, handle.level), relationshipCounts: relationship.counts },\n      records: recordsResult.records.map(knowledgeSummary),\n      recordsNextCursor: recordsResult.nextCursor\n        ? this.#mintCursor(binding, handle.level, 'records', recordsResult.nextCursor)\n        : undefined,\n      mentioningRecords: mentioningRecords.map(knowledgeSummary),\n      mentioningRecordsNextCursor: mentioningResult.nextCursor\n        ? this.#mintCursor(binding, handle.level, 'mentioning-records', mentioningResult.nextCursor)\n        : undefined,\n      outgoingTargets: {\n        nodes: outgoingTargets.nodes,\n        partial: outgoingTargets.partial || Boolean(recordsResult.nextCursor),\n      },\n      incomingParents: {\n        nodes: incomingParents.nodes,\n        partial: incomingParents.partial || Boolean(mentioningResult.nextCursor),\n      },\n      relationshipCounts: relationship.counts,\n      content: node.content === undefined ? undefined : content.value,\n      contentTruncated: content.truncated,\n      links,\n    };\n  }\n\n  async listActivity(input: {\n    level: KnowledgeInspectorScopeLevel;\n    cursor?: string;\n    limit?: number;\n  }): Promise<KnowledgeInspectorActivityList> {\n    const binding = await this.#binding();\n    const scope = this.#scope(binding, input.level);\n    const limit = boundedLimit(input.limit, DEFAULT_ACTIVITY_LIMIT, MAX_ACTIVITY_LIMIT);\n    const after = this.#consumeCursor(input.cursor, binding, input.level, 'activity');\n    const events = await this.#knowledge.listActivity({ scope, after, limit });\n    const activityEvents: KnowledgeInspectorActivityEvent[] = [];\n    for (const event of events) {\n      const record = await this.#activityRecord(event, scope, binding, input.level);\n      activityEvents.push({\n        action: event.action,\n        recordType: event.recordType,\n        scope: scopeBadge(event.scope),\n        sourceThreadId: record ? event.sourceThreadId : undefined,\n        createdAt: event.createdAt.toISOString(),\n        record,\n      });\n    }\n    await this.#assertStable(binding);\n    return {\n      identityKey: binding.identityKey,\n      scopeLevel: input.level,\n      events: activityEvents,\n      nextCursor:\n        events.length === limit ? this.#mintCursor(binding, input.level, 'activity', events.at(-1)!.id) : undefined,\n    };\n  }\n\n  async #binding(): Promise<Binding> {\n    // Scope rungs come from the same resolver the subconscious writes under; an\n    // owner id is a USER id and never names a knowledge org.\n    const identity = resolveKnowledgeScopeIdentity(this.#session.state.get());\n    const sessionResourceId = this.#session.identity.getResourceId();\n    if (!identity.resolved) {\n      // An unresolved org is its own identity: handles minted under the\n      // previous scope must not survive into whatever resolves next.\n      this.#invalidateIdnode();\n      throw new KnowledgeInspectorError(\n        'unavailable',\n        identity.reason\n          ? `Knowledge inspection unavailable: ${identity.reason}`\n          : 'Knowledge inspection requires a resolved organization for this session.',\n      );\n    }\n    if (!sessionResourceId) {\n      throw new KnowledgeInspectorError('unavailable', 'Knowledge inspection requires an active project.');\n    }\n    const organizationId = identity.organizationId;\n    const resourceId = identity.knowledgeResourceId ?? sessionResourceId;\n    const activeThreadId = this.#session.thread.getId() ?? undefined;\n    const thread = activeThreadId ? await this.#session.thread.getById({ threadId: activeThreadId }) : null;\n    const threadId = thread?.resourceId === sessionResourceId ? thread.id : undefined;\n    const fingerprint = `${organizationId}\\0${resourceId}\\0${threadId ?? ''}`;\n    if (this.#fingerprint !== fingerprint) {\n      this.#fingerprint = fingerprint;\n      this.#identityKey = opaqueToken();\n      this.#handles.clear();\n      this.#cursors.clear();\n    }\n    return { organizationId, resourceId, threadId, fingerprint, identityKey: this.#identityKey };\n  }\n\n  #scope(binding: Binding, level: KnowledgeInspectorScopeLevel): KnowledgeScope {\n    if (level === 'org') return [`org:${binding.organizationId}`];\n    const scope = [`org:${binding.organizationId}`, `resource:${binding.resourceId}`];\n    if (level === 'resource') return scope;\n    if (!binding.threadId) {\n      throw new KnowledgeInspectorError('unavailable', 'The active thread does not belong to this project.');\n    }\n    return [...scope, `thread:${binding.threadId}`];\n  }\n\n  async #assertStable(binding: Binding): Promise<void> {\n    const current = await this.#binding();\n    if (current.identityKey !== binding.identityKey || current.fingerprint !== binding.fingerprint) {\n      throw new KnowledgeInspectorError('stale-handle', 'Knowledge scope changed while the request was running.');\n    }\n  }\n\n  #assertVisible<T extends KnowledgeNode>(record: T | null, scope: KnowledgeScope): asserts record is T {\n    if (!record || !isKnowledgeScopeVisible(record.scope, scope)) {\n      throw new KnowledgeInspectorError('not-visible', 'Knowledge record is not visible in the selected scope.');\n    }\n  }\n\n  #recordSummary(\n    record: KnowledgeNode,\n    binding: Binding,\n    level: KnowledgeInspectorScopeLevel,\n  ): KnowledgeInspectorNodeSummary {\n    const type: KnowledgeInspectorRecordType = 'node';\n    return {\n      handle: this.#mintHandle(binding, level, type, record.id),\n      type,\n      name: record.name,\n      kind: record.kind,\n      scope: scopeBadge(record.scope),\n      version: record.version,\n      updatedAt: record.updatedAt.toISOString(),\n    };\n  }\n\n  async #rankedNodeSnapshot(\n    scope: KnowledgeScope,\n    namePrefix: string | undefined,\n    kind: string | undefined,\n    sort: Exclude<KnowledgeInspectorNodeSort, 'recent'>,\n  ): Promise<RankedNodeSnapshot> {\n    const records = await this.#knowledge.listNodes({\n      scope,\n      namePrefix,\n      kind,\n      limit: MAX_RANK_CANDIDATES,\n    });\n    const ranked = await Promise.all(\n      records.map(async (node, recencyRank) => ({\n        node,\n        recencyRank,\n        ...(await this.#sampledRelationshipCounts(node, scope)),\n      })),\n    );\n    const connected = [...ranked].sort(\n      (a, b) => b.degree - a.degree || a.recencyRank - b.recencyRank || a.node.id.localeCompare(b.node.id),\n    );\n    const connectedRank = new Map(connected.map((entry, index) => [entry.node.id, index]));\n    const ordered =\n      sort === 'connected'\n        ? connected\n        : [...ranked].sort((a, b) => {\n            const aScore = 1 / (RRF_K + a.recencyRank + 1) + 1 / (RRF_K + connectedRank.get(a.node.id)! + 1);\n            const bScore = 1 / (RRF_K + b.recencyRank + 1) + 1 / (RRF_K + connectedRank.get(b.node.id)! + 1);\n            return bScore - aScore || a.recencyRank - b.recencyRank || a.node.id.localeCompare(b.node.id);\n          });\n    return {\n      offset: 0,\n      entries: ordered.map(entry => ({ id: entry.node.id, degree: entry.degree, counts: entry.counts })),\n    };\n  }\n\n  async #sampledRelationshipCounts(\n    node: KnowledgeNode,\n    scope: KnowledgeScope,\n  ): Promise<{ degree: number; counts: KnowledgeInspectorRelationshipCounts }> {\n    const [aboutResult, mentioningResult] = await Promise.all([\n      this.#knowledge.listKnowledgeAbout({ node: node.id, scope, limit: MAX_RANK_FACTS }),\n      this.#knowledge.listKnowledgeMentioning({ node: node.id, scope, limit: MAX_RANK_FACTS }),\n    ]);\n    const [outgoing, incoming] = await Promise.all([\n      this.#outgoingNodeRecords(node, aboutResult.records, scope),\n      this.#incomingParentRecords(node, mentioningResult.records, scope),\n    ]);\n    const mentioningRecords = mentioningResult.records.filter(record => record.node !== node.id);\n    const degree = new Set([...outgoing.nodes, ...incoming.nodes].map(record => record.id)).size;\n    return {\n      degree,\n      counts: {\n        records: aboutResult.records.length + mentioningRecords.length,\n        outgoing: outgoing.nodes.length,\n        incoming: incoming.nodes.length,\n        sampled: Boolean(\n          aboutResult.nextCursor || mentioningResult.nextCursor || outgoing.truncated || incoming.truncated,\n        ),\n      },\n    };\n  }\n\n  async #outgoingNodeRecords(\n    current: KnowledgeNode,\n    records: KnowledgeRecord[],\n    scope: KnowledgeScope,\n  ): Promise<RelationshipRecords> {\n    const related = new Map<string, KnowledgeNode>();\n    let truncated = false;\n    const sources = [current.content ?? '', ...records.map(record => record.text)];\n    for (const source of sources) {\n      for (const name of parseKnowledgeWikilinks(source)) {\n        if (related.size >= MAX_RELATED_RECORDS) {\n          truncated = true;\n          break;\n        }\n        const node = await this.#knowledge.resolveNode({ name, scope });\n        if (node && node.id !== current.id && isKnowledgeScopeVisible(node.scope, scope)) {\n          related.set(node.id, node);\n        }\n      }\n      if (truncated) break;\n    }\n    return { nodes: [...related.values()], truncated };\n  }\n\n  async #incomingParentRecords(\n    current: KnowledgeNode,\n    records: KnowledgeRecord[],\n    scope: KnowledgeScope,\n  ): Promise<RelationshipRecords> {\n    const related = new Map<string, KnowledgeNode>();\n    let truncated = false;\n    for (const record of records) {\n      if (record.node === current.id || related.has(record.node)) continue;\n      if (related.size >= MAX_RELATED_RECORDS) {\n        truncated = true;\n        break;\n      }\n      const node = await this.#knowledge.getNode(record.node);\n      if (node && isKnowledgeScopeVisible(node.scope, scope)) related.set(node.id, node);\n    }\n    return { nodes: [...related.values()], truncated };\n  }\n\n  async #outgoingTargets(\n    current: KnowledgeNode,\n    records: KnowledgeRecord[],\n    scope: KnowledgeScope,\n    binding: Binding,\n    level: KnowledgeInspectorScopeLevel,\n  ): Promise<KnowledgeInspectorRelationshipPreview> {\n    const related = await this.#outgoingNodeRecords(current, records, scope);\n    return {\n      nodes: related.nodes.map(node => this.#recordSummary(node, binding, level)),\n      partial: related.truncated,\n    };\n  }\n\n  async #incomingParents(\n    current: KnowledgeNode,\n    records: KnowledgeRecord[],\n    scope: KnowledgeScope,\n    binding: Binding,\n    level: KnowledgeInspectorScopeLevel,\n  ): Promise<KnowledgeInspectorRelationshipPreview> {\n    const related = await this.#incomingParentRecords(current, records, scope);\n    return {\n      nodes: related.nodes.map(node => this.#recordSummary(node, binding, level)),\n      partial: related.truncated,\n    };\n  }\n\n  async #activityRecord(\n    event: KnowledgeActivityEvent,\n    scope: KnowledgeScope,\n    binding: Binding,\n    level: KnowledgeInspectorScopeLevel,\n  ): Promise<KnowledgeInspectorNodeSummary | undefined> {\n    if (event.recordType === 'node') {\n      const node = await this.#knowledge.getNode(event.recordId);\n      return node && isKnowledgeScopeVisible(node.scope, scope) ? this.#recordSummary(node, binding, level) : undefined;\n    }\n    const record = await this.#knowledge.getKnowledge({ id: event.recordId, includeDeleted: true });\n    if (!record || !isKnowledgeScopeVisible(record.scope, scope)) return undefined;\n    const node = await this.#knowledge.getNode(record.node);\n    return node && isKnowledgeScopeVisible(node.scope, scope) ? this.#recordSummary(node, binding, level) : undefined;\n  }\n\n  #mintHandle(\n    binding: Binding,\n    level: KnowledgeInspectorScopeLevel,\n    type: KnowledgeInspectorRecordType,\n    recordId: string,\n  ): string {\n    this.#pruneOpaqueEntries();\n    const token = opaqueToken();\n    this.#handles.set(token, {\n      identityKey: binding.identityKey,\n      level,\n      type,\n      recordId,\n      expiresAt: Date.now() + HANDLE_TTL_MS,\n    });\n    return token;\n  }\n\n  #readHandle(handle: string, binding: Binding, expectedType: KnowledgeInspectorRecordType): HandleEntry {\n    const entry = this.#handles.get(handle);\n    if (!entry || entry.expiresAt < Date.now() || entry.type !== expectedType) {\n      throw new KnowledgeInspectorError('invalid-handle', 'Knowledge record handle is invalid or expired.');\n    }\n    if (entry.identityKey !== binding.identityKey) {\n      throw new KnowledgeInspectorError('stale-handle', 'Knowledge record handle belongs to a previous scope.');\n    }\n    return entry;\n  }\n\n  #mintCursor(\n    binding: Binding,\n    level: KnowledgeInspectorScopeLevel,\n    kind: CursorEntry['kind'],\n    value: string,\n    filters?: CursorEntry['filters'],\n  ): string {\n    this.#pruneOpaqueEntries();\n    const token = opaqueToken();\n    this.#cursors.set(token, {\n      identityKey: binding.identityKey,\n      level,\n      kind,\n      value,\n      filters,\n      expiresAt: Date.now() + HANDLE_TTL_MS,\n    });\n    return token;\n  }\n\n  #consumeCursor(\n    cursor: string | undefined,\n    binding: Binding,\n    level: KnowledgeInspectorScopeLevel,\n    kind: CursorEntry['kind'],\n    filters?: CursorEntry['filters'],\n  ): string | undefined {\n    if (!cursor) return undefined;\n    const entry = this.#cursors.get(cursor);\n    if (\n      !entry ||\n      entry.expiresAt < Date.now() ||\n      entry.identityKey !== binding.identityKey ||\n      entry.level !== level ||\n      entry.kind !== kind ||\n      entry.filters?.namePrefix !== filters?.namePrefix ||\n      entry.filters?.kind !== filters?.kind ||\n      entry.filters?.sort !== filters?.sort\n    ) {\n      throw new KnowledgeInspectorError(\n        'invalid-cursor',\n        'Knowledge cursor does not match the active scope and filters.',\n      );\n    }\n    return entry.value;\n  }\n\n  #pruneOpaqueEntries(): void {\n    const now = Date.now();\n    for (const [token, entry] of this.#handles) {\n      if (entry.expiresAt < now) this.#handles.delete(token);\n    }\n    for (const [token, entry] of this.#cursors) {\n      if (entry.expiresAt < now) this.#cursors.delete(token);\n    }\n    while (this.#handles.size + this.#cursors.size >= MAX_OPAQUE_ENTRIES) {\n      const handle = this.#handles.keys().next().value;\n      if (handle) this.#handles.delete(handle);\n      else {\n        const cursor = this.#cursors.keys().next().value;\n        if (cursor) this.#cursors.delete(cursor);\n        else break;\n      }\n    }\n  }\n\n  #invalidateIdnode(): void {\n    this.#fingerprint = undefined;\n    this.#identityKey = opaqueToken();\n    this.#handles.clear();\n    this.#cursors.clear();\n  }\n}\n\nexport async function createKnowledgeInspector(input: {\n  storage: MastraCompositeStore;\n  knowledge?: Knowledge | string;\n  mastra?: Pick<Mastra, 'getKnowledge'>;\n  session: Session<MastraCodeState>;\n}): Promise<KnowledgeInspector | undefined> {\n  let selected: Knowledge | undefined;\n  if (typeof input.knowledge === 'string') {\n    try {\n      selected = input.mastra?.getKnowledge(input.knowledge);\n    } catch {\n      throw new KnowledgeInspectorError('unavailable', 'The configured Knowledge runtime is unavailable.');\n    }\n    if (!selected) {\n      throw new KnowledgeInspectorError('unavailable', 'The configured Knowledge runtime is unavailable.');\n    }\n  } else {\n    selected = input.knowledge;\n  }\n  const knowledge = selected ? await selected.getStorage() : await input.storage.getStore('knowledge');\n  return knowledge ? new ScopedKnowledgeInspector({ knowledge, session: input.session }) : undefined;\n}\n"],"mappings":"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"}

package/dist/knowledge-scope.d.ts

@@ -0,0 +1,35 @@
+import type { MastraCodeState } from './schema.js';
+/**
+ * The organization rung local (TUI/studio) knowledge is curated under. A fixed
+ * literal on purpose: deriving it from a hostname, machine id, or path would
+ * fragment local knowledge per machine or checkout, and a user running several
+ * machines against one shared store could never share knowledge between them.
+ * Resolving a real org id (settings, /knowledge, login) is future work; when it
+ * lands, it replaces this default here.
+ */
+export declare const LOCAL_KNOWLEDGE_ORG_ID = "local";
+export type KnowledgeScopeIdentity = {
+    resolved: true;
+    organizationId: string;
+    /** Set when the resource rung is anchored on something other than the session resource. */
+    knowledgeResourceId?: string;
+} | {
+    resolved: false;
+    knowledgeResourceId?: string;
+    reason?: string;
+};
+/**
+ * The single source of truth for which org/resource rungs a session's knowledge
+ * lives under. Every reader and writer of the knowledge store (the subconscious
+ * memory factory, the /knowledge inspector) must derive its scope from here so
+ * that what curation writes is what the browser reads.
+ *
+ * - Factory seeds the authoritative org id into session state. There is no
+ *   fallback: a session owner is a USER id, never an organization, so a
+ *   Factory-owned session without an org resolves to nothing (fail closed).
+ * - Factory runs share one knowledge graph per project, so the resource rung is
+ *   anchored on the project id.
+ * - TUI/studio sessions use {@link LOCAL_KNOWLEDGE_ORG_ID}.
+ */
+export declare function resolveKnowledgeScopeIdentity(state: MastraCodeState | undefined): KnowledgeScopeIdentity;
+//# sourceMappingURL=knowledge-scope.d.ts.map

package/dist/knowledge-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-scope.d.ts","sourceRoot":"","sources":["../src/knowledge-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C,MAAM,MAAM,sBAAsB,GAC9B;IACE,QAAQ,EAAE,IAAI,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,2FAA2F;IAC3F,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GACD;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,GAAG,sBAAsB,CAoBxG"}