@agimon-ai/po-help 0.0.0-alpha.105 → 0.0.0-alpha.107

package/dist/extensions/server.cjs

@@ -63,6 +63,145 @@ var root_server_default$1 = (0, _agimon_ai_po_core_extensionFile.defineRoot)((co
 	services: context.host.scope === "workspace" ? [brainSimulationProvider] : []
 }));
 //#endregion
+//#region src/types/brainGraph.ts
+const BRAIN_GRAPH_KINDS = [
+	"backend",
+	"web",
+	"native"
+];
+const CODEMODE_SERVICE = "po/codemode";
+const PLUMBING_SERVICES = /* @__PURE__ */ new Set([
+	"po/server-scope",
+	"po/server-host",
+	"po/headless-host",
+	"po/global-services"
+]);
+function graphOf(nodes, links) {
+	const linked = new Set([...links.values()].flatMap((link) => [link.source, link.target]));
+	return {
+		nodes: [...nodes.values()].filter((node) => linked.has(node.id)).sort((a, b) => a.id.localeCompare(b.id)),
+		links: [...links.values()].sort((a, b) => `${a.source}\0${a.target}`.localeCompare(`${b.source}\0${b.target}`))
+	};
+}
+/**
+* Public services, services a code-mode contributor can call (every service a plugin that injects
+* po/codemode resolves), and the plugins that consume them. Nodes collapse by name across scopes.
+* A nested fiber is an intermediary, so its injections fold into the plugin that owns it; unowned
+* fibers, unresolved injections and scope plumbing are left out.
+*/
+function backendGraph(snapshot) {
+	const plugins = new Map(snapshot.consumers.flatMap((consumer) => consumer.owner.kind === "package" && consumer.owner.packageName ? [[consumer.id, {
+		name: consumer.owner.packageName,
+		origin: consumer.owner.origin
+	}]] : []));
+	const services = new Map(snapshot.services.map((service) => [service.id, service]));
+	const uses = snapshot.edges.flatMap((edge) => {
+		const plugin = plugins.get(edge.consumer);
+		const service = edge.service === null ? void 0 : services.get(edge.service);
+		return plugin && service && !PLUMBING_SERVICES.has(service.name) ? [{
+			plugin,
+			service
+		}] : [];
+	});
+	const contributors = new Set(uses.filter((use) => use.service.name === CODEMODE_SERVICE).map((use) => use.plugin.name));
+	const reachable = new Set(uses.filter((use) => contributors.has(use.plugin.name)).map((use) => use.service.name));
+	const nodes = /* @__PURE__ */ new Map();
+	const links = /* @__PURE__ */ new Map();
+	for (const { plugin, service } of uses) {
+		if (!service.public && !reachable.has(service.name)) continue;
+		const serviceId = `service:${service.name}`;
+		const previous = nodes.get(serviceId);
+		if (!previous || service.description && previous.detail.endsWith("No description.")) nodes.set(serviceId, {
+			id: serviceId,
+			label: service.name,
+			role: reachable.has(service.name) ? "codemode" : "public",
+			detail: `${service.public ? "Public" : "Private"} service${reachable.has(service.name) ? ", callable from code mode" : ""}. Provided by ${service.owner.packageName ?? service.owner.kind}. ${service.description ?? "No description."}`
+		});
+		const pluginId = `plugin:${plugin.name}`;
+		nodes.set(pluginId, {
+			id: pluginId,
+			label: plugin.name,
+			role: plugin.origin === "personal" ? "personal" : "plugin",
+			detail: `Plugin${contributors.has(plugin.name) ? " that contributes to code mode" : ""}.`
+		});
+		links.set(`${pluginId}\0${serviceId}`, {
+			source: pluginId,
+			target: serviceId,
+			label: "consumes"
+		});
+	}
+	return graphOf(nodes, links);
+}
+/** Each plugin and the slots it fills or declares, for one client host. */
+function clientGraph(packages, target, hostSlots = {}) {
+	const hostDescriptions = new Map(Object.values(hostSlots).map((slot) => [slot.slot, slot.description]));
+	const nodes = /* @__PURE__ */ new Map();
+	const links = /* @__PURE__ */ new Map();
+	const slot = (name, description) => {
+		const id = `slot:${name}`;
+		if (!nodes.has(id) || description) nodes.set(id, {
+			id,
+			label: name,
+			role: "slot",
+			detail: `Slot. ${description ?? hostDescriptions.get(name) ?? "No description."}`
+		});
+		return id;
+	};
+	for (const pkg of packages) {
+		const metadata = target === "web" ? pkg.web : pkg.native;
+		if (!metadata || !pkg.owner.packageName) continue;
+		const pluginId = `plugin:${pkg.owner.packageName}`;
+		nodes.set(pluginId, {
+			id: pluginId,
+			label: pkg.owner.packageName,
+			role: pkg.owner.origin === "personal" ? "personal" : "plugin",
+			detail: `Plugin with a ${target} half.`
+		});
+		for (const declared of metadata.slots) {
+			const slotId = slot(declared.name, declared.description);
+			links.set(`${pluginId}\0${slotId}`, {
+				source: pluginId,
+				target: slotId,
+				label: "declares"
+			});
+		}
+		for (const fill of metadata.fills) {
+			if (fill.slot === null) continue;
+			const slotId = slot(fill.slot);
+			links.set(`${pluginId}\0${slotId}`, {
+				source: pluginId,
+				target: slotId,
+				label: "fills"
+			});
+		}
+	}
+	return graphOf(nodes, links);
+}
+/** One essential graph. Web prefers the exact browser mount inventory; native reads installed packages. */
+function brainGraph(snapshot, kind, hostSlots) {
+	if (kind === "backend") return backendGraph(snapshot);
+	return clientGraph(kind === "web" ? snapshot.clientPackages ?? snapshot.packages : snapshot.packages, kind, hostSlots);
+}
+/** A node and its direct connections in one graph, or undefined when the graph lacks it. */
+function brainNodeView(graph, kind, id) {
+	const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+	const node = byId.get(id);
+	if (!node) return void 0;
+	return {
+		kind,
+		node,
+		links: graph.links.flatMap((link) => link.source === id ? [{
+			label: link.label,
+			direction: "out",
+			node: byId.get(link.target)
+		}] : link.target === id ? [{
+			label: link.label,
+			direction: "in",
+			node: byId.get(link.source)
+		}] : [])
+	};
+}
+//#endregion
 //#region src/services/brain/index.ts
 function createBrain(options) {
 	const services = (signal) => {
@@ -154,14 +293,39 @@ function createBrain(options) {
 const DECLARATIONS$1 = `type Scope = { id: string; level: 'global' | 'workspace' | 'session' };
 type Owner = { kind: 'host' | 'package' | 'unknown'; packageName: string | null; origin: 'po' | 'personal' | 'unknown' };
 interface WebMetadata { version: 1; slots: { name: string; scope: Scope['level']; description?: string; parent?: string; kind: 'data' | 'component' }[]; fills: { id: string; slot: string | null; scope: Scope['level']; placement: 'verified' | 'unverified' }[]; diagnostics: string[] }
-interface PackageMetadata { scope: Scope; owner: Owner; web: WebMetadata | null }
+interface PackageMetadata { scope: Scope; owner: Owner; web: WebMetadata | null; native?: WebMetadata | null }
 interface ServicesSnapshot { scope: Scope; scopes: Scope[]; packages: PackageMetadata[]; clientPackages?: PackageMetadata[]; services: { id: string; name: string; scope: Scope; visibleFrom: Scope; owner: Owner; public: boolean; description: string | null }[]; consumers: { id: string; name: string; scope: Scope; owner: Owner }[]; edges: { consumer: string; service: string | null; name: string; status: 'resolved' | 'waiting' }[]; diagnostics: string[] }
 interface SlotsSnapshot { scope: Scope; scopes: Scope[]; slots: { id: string; name: string; scope: Scope; owner: Owner; description: string | null; parent: string | null; kind: 'data' | 'component' }[]; fills: { id: string; slot: string | null; scope: Scope; owner: Owner; placement: 'verified' | 'unverified' }[]; diagnostics: string[] }
-declare const brain: { services(): Promise<ServicesSnapshot>; slots(): Promise<SlotsSnapshot> };`;
+type GraphKind = 'backend' | 'web' | 'native';
+type Role = 'public' | 'codemode' | 'plugin' | 'personal' | 'slot';
+interface GraphNode { id: string; label: string; role: Role; detail: string }
+/** backend: plugin -consumes-> service. web/native: plugin -fills|declares-> slot. */
+interface Graph { kind: GraphKind; nodes: GraphNode[]; links: { source: string; target: string; label: string }[] }
+interface NodeView { kind: GraphKind; node: GraphNode; links: { label: string; direction: 'out' | 'in'; node: GraphNode }[] }
+declare const brain: {
+  /** The essential map the Brain page draws. Ids look like 'plugin:@scope/name', 'service:po/fs', 'slot:page'. */
+  graph(input?: { kind?: GraphKind }): Promise<Graph>;
+  /** One node and its direct links in every graph that has it, or only in kind. Empty when absent. */
+  node(input: { id: string; kind?: GraphKind }): Promise<NodeView[]>;
+  /** Raw snapshot with fibers, private services, waiting injections and diagnostics. */
+  services(): Promise<ServicesSnapshot>;
+  /** Raw web slot declarations, parent links and fill placements. */
+  slots(): Promise<SlotsSnapshot>;
+};`;
+function graphKind(value) {
+	if (value === void 0) return "backend";
+	if (BRAIN_GRAPH_KINDS.includes(value)) return value;
+	throw new Error(`kind must be one of ${BRAIN_GRAPH_KINDS.join(", ")}.`);
+}
+function input(value) {
+	if (value === void 0) return {};
+	if (value !== null && typeof value === "object" && !Array.isArray(value)) return value;
+	throw new Error("Expected an options object.");
+}
 function createBrainNamespace(options) {
 	return {
 		name: "brain",
-		summary: "Inspect scoped service ownership, declared dependencies and slot metadata. Read-only, Help mode.",
+		summary: "Explore the essential service and slot graphs (backend, web, native) and raw service and slot snapshots. Read-only, Help mode.",
 		declarations: DECLARATIONS$1,
 		bind(run) {
 			if (run.sessionId !== options.sessionId) throw new Error("The brain namespace belongs to another session.");
@@ -170,6 +334,24 @@ function createBrainNamespace(options) {
 				options.assertActive();
 			};
 			return {
+				graph: async (options_) => {
+					check();
+					const kind = graphKind(input(options_).kind);
+					return {
+						kind,
+						...brainGraph(options.service.services(run.signal), kind, _agimon_ai_po_core_serverPlugin.HOST_SLOT_METADATA)
+					};
+				},
+				node: async (options_) => {
+					check();
+					const { id, kind } = input(options_);
+					if (typeof id !== "string" || !id.trim() || id.length > 1024) throw new Error("id must be a node id string.");
+					const snapshot = options.service.services(run.signal);
+					return (kind === void 0 ? BRAIN_GRAPH_KINDS : [graphKind(kind)]).flatMap((each) => {
+						const view = brainNodeView(brainGraph(snapshot, each, _agimon_ai_po_core_serverPlugin.HOST_SLOT_METADATA), each, id);
+						return view ? [view] : [];
+					});
+				},
 				services: async () => {
 					check();
 					return options.service.services(run.signal);